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ViSTA™ 

Before Your 
Clients Start 
Disappearing 1 .. 

Black holes may be an 
interesting phenomenon 
in outer space, but not in 
your software testing. We 
have helped 100'$ of 
companies like yours, on 
over 200 million lines of 
code, verify an amazing 
fact: less than 40% of 
"production level" code is 
being tested. Now that is 
a major "black hole", 

... Into the 

Unknown. 


A POWERFUL SET OF ENTERPRISE TESTING TOOLS 

VlstaTEST-OS/2 

VistaSIM 

VistaGRAPH 

• C/C++ 

• Client/Server 

* Metric summary 

* Multi platform 

Testing 

* Flexible 

* Unit level testing 

* Reuse Testing 

Spreadsheet 

* Complexity Metrics 

* Automate Error 
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Handling Test 
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Multi conditional, 
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UNIX POWER TOOLS 
NOW ON OS/2 


IBM 
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NOVELL 


HP 
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ARBOR 

OSF 
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DIGITAL 
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ViSTA tools help increase the 
quality of your application, isolate 
dead code and improve your 
client/server testing. 

Call 1-800-258-8649 today for a 

Free Evaluation. 

FAX at 408-562-4334 or e-mail vsales@verita 5 .c 0 m 

Be sure to ask about our 
OS/2 Enterprise Workgroup 
for extra savings. 

VERITAS ViSTA, VstaSlM, ViataGRAPH and VstaTEST are rrademarlss of VERITAS Software. 
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Introductory Offer 
• Enterprise Edition $1,650-00 


■ Bronze Edition 

(Local DB2/2 access Only) 


Regular Price 
Royalty-free runtime 


$2,850,00 
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TechBridge makes 
Client/Server Development 

Your application is only a few mouse clicks away 



point-and-Click Ties GUI Fields to Data 

Automatically connect GUI fields to your database, and you have a 
form Lhat can view and update data. Or import table definitions and let 
us auto-design a quick form for you to do query or present the data in 
3-D business charts. Access DB2/2 and the whole DB2 family 
through DDCS/2; or Oracle 7 or 50 more data sources through 
EDA/SQL middleware. With TechBridge Builder you can do all this, 
with just drag-and-drop, poim-and-cliek and absolutely NO CODING 
because so much is AUTOMATED, 

Visual Development 

Place a pre defined control group from your reuse library and attach 
business logic or context sensitive help. Double-click to preview. 
Design a modal dialog or an advanced OQUI workplace with point- 
and-click. Use drag-and-drop to tie your objects together into an 
application, then let our packager produce the executables for you. 

Scripting 

Double click on a form control and enter an event driven script, e.g. 
Multiply Principle by Interest giving Amount. Yes, it’s just COBOL, 
Click to compile it. Click again to lest it. Click to invoke the debugger. 
Iterative rapid development? You bet! 


Object Technology 

With TechBridge Builder you get a complete set of classes, the 
practical building blocks that you can tailor to build your 
application. Supporting these classes is a framework with over 
700 base classes and 24,000 methods - a knowledge base of 
technology like CUA ’Of SQL, PM, and human factors. Don't 
waste time crafting your own framework, build on ours and 
jump right into building applications that meel your specific 
needs. 

on Your System 

The minimum system requirement is an 8M OS/2 machine with 
l OM of free disk space. It s LAN enabled. 








1 - 800 - 463-8998 



TechBridge 

Technology Corp. 


Tech Bridge Technology Corp. 5001 Yonge St., Suiie 1301, North York, Ontario, Canada M2N 6P6 Phone: (416) 222-8998 Fax: (416) 222-0168 
Pliers and specification are subject to change without notice. Price does not include freight and taxes where applicable. Prices quoted in US dollar*. TechBridge. TechBridge Technology and TechBridge Builder 
are registered trademark* of TechBri dge Technology Corp. ©1994 TechBridge Technology Corp. All other brand and product names are trademarks or registered trademarks of their respective companies. 
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With so many advanced features 
in Micro Focus COBOL, there’s 
one you may have overlooked. 


The Future. 

At Micro Focus, we have a history of ensuring 
a bright future for our customers. 

Fifteen years ago, when the “future” was per¬ 
sonal computers, we brought the First true business 
application development environment to the desk¬ 
top. Over the years, we built on that foundation by 
providing the tools and utilities that delivered new 
levels of productivity to programmers. 

Today, we’re ready for the next step: 
Introducing Object COBOL”—the first true object 
oriented business programming environment. 

The Micro Focus Object COBOL Option pro¬ 
vides all the functionality you would expect from 


an object-oriented development environment— 
including encapsulation, polymorphism and 
inheritance. It also brings all the benefits of object 
orientation—reusability, real-world modeling and 
increased maintainability—to COBOL program¬ 
mers w ithout discarding existing investments in 
code and skills. 

Object COBOL is shipped with a library of 
classes for managing collections of objects and 
for creating Graphical User Interfaces. These 
classes can be accessed and extended with 
another Object COBOL component, the Browser. 

Object COBOL even extends the COBOL 
language by letting you define syntax that best 


suits your business needs. Object COBOL’s 
unique vocabularies make applications easier to 
read, write and understand... for programmers 
and end-users alike! 

And the best pan? It’s designed for COBOL 
programmers, so w ith Micro Focus, if you know 
COBOL, you’re ready for an object-oriented 
future today. 

For the latest update on this new technology, 
call 80Q-MF-COBOL and ask for our white paper: 
The Object Oriented COBOL Model. 

Micro Focus: The past, present, and future of 
programming. 


MICRO FOCUS® 


Micro Foci* b a rcgptcfcd trademark of Micro Foci* Lid. Object COBOL b a trademark of Micro Fuci» 
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Superset/2 

by Soft ouch Systems 

The SuperSet /2 gives REXX the power of C by 
providing interfaces to LAN Server, NetBIOS, 
TCP/IP and Communications Manager/2. and 
by providing access to low level system facilities, 
including processes, threads, semaphores, 
names pipes, and VIO commands The 
SuperSet/2 complements visual REXX program¬ 
ming packages. The 600+ page manual fully documents over 300 
functions in 7 DLLs ready to supercharge your REXX! 



List: $80 


Ours: $69 FAXwtum #: 3621-0002 


RimStar Programmer’s Editor 

by RimStar Technology, Inc. 

Features: 32-blt GUL Syntax Coloring, 
ANSI “CT macro language, “C" Source 
Browser, unlimited redo/undo, no lim¬ 
its on number of flies, windows, or line 
length. Emulates BRIEF plus many 
other editors. Coin pile/jump to error, 
hex editing, smart Indenting, book¬ 
marks, completely configurable key¬ 
board mappings, WF/2 enabled and much more. Window fit NT 
version available. 

List: $299 Ours: $259 FAX««ra #: 1013-0901 
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Visual SlickEdit for OS/2 

by MicroEdge 

The same great programmers' editor that 
gave you extensive language support, project 
management, and superb editing features is 
now available on OS/2! Users of Visual 
SlickEdit for Windows or NT don't have to 
rewrite their macros when switching to 
OS/2. Macro source, dialog templates, and 
bitmaps arc binary-compatible with Visual 
SlickEdit on all other platforms, 30 day 
risk-free trial! 



List: $295 


Ours: $199 FAXatem #: 1997-0002 


The Object Factory—IDL 

by Synaptec, Inc. 

IDL development environment for OS/2 
SOM. Includes multiple inheritance, 
framework filters. Drag drop backup 
and restore, a SOM class browser, on¬ 
line help and much more. Use class develop¬ 
ment notebooks to create new classes Just by 
dropping them on the class browser. Eliminate the complexities of 
SOM programming. Framework fillers focus development providing 
quicker access to the hundreds of SOM classes. View every inherited 
method from every parent In one list box. Manage class development 
with great ease and little effort. 

List: $250 Ours: $229 FAXcetcra 4: 1012-5402 
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„ IBM OS/2 Warp v3 

by IBM 

OS/2 Warp Version 3, the reliable 32-bit 
GW* operating system, makes computing easier 

■K* Features include a launch pad for easy access 

” to your frequently used applications, built-in 
__ ,vnr) //V,rn multimedia support, 3D animated icons and 
H l (iff / one-button install. Every copy includes a 

BonusPak for no extra charge. This BonusPak 
provides you with a complete set of tools for accessing and navigating 
the Internet; IBM Works—a suite of 32-bit applications; FaxWorks for 
OS/2; HyperACCESS Ute; IBM Person to Person'; and much more. 
Systems with 4MB of memory are now supported. 

List: $129 Ours: $79 FA Xcctem #: 3142-0035 
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c-tree Plus 

by FairCom 

fly jB DOS • WINDOWS • NT ■ UNIX - OS/2 • SUN ♦ 

A4 SW RS6000 * HP9000 • MAC • QNX • BANYAN ■ 

SCO. This well known, highly portable data 
management package has become established 
as the tool of choice for commercial develop¬ 
ment. Offering unprecedented data control, 
choose from direct low level access, ISAM level, 
or SQL access with the FairCom Server. Single User. Multiuser, or 
optional Client /Server, ANSI Standard, Full Source, No Royalties. 

List: $595 Ours: $495 FAXcelem #: 1381-0004 
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FAIRCOM* 

sine# 1979 


EZRAID 

by PRO Engineering, Inc. 

EZRAID PRO is the OS/2 software solution 
that provides the same full powered RAID 
benefits found in hardware systems world¬ 
wide. With its unique technology, EZRAID 
PRO increases system performance, simplifies 
data management find ensures complete fault 
tolerance. EZRAID PRO supports spanning, 

RAID levels 0.1,4 and 5: is compatible with 
SCSI, IDE and ESDI: and is Ready for Warp 
and LAN Server 4.0- 

Lite List: $195 Ours: $188 

PRO List: $795 Ours: $764 

FAXcmmtl 1016-5101 
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To order coll: 800-445-7899 

Corporate Developer Division: 800 441-1511 
FAX: 90S 389-9227 
international: 90S 389-9228 
Customer Service: 90S 389-9229 
Programmer's Paradise Deutschland: 
Teh: 03121/79073 * FAX; 08121/76566 
Programmer's Paradise Italia; 
Tel,: 39-2-967-00409 * FAX: 39-2-967-02855 
Programmer's Paradise United Kingdom: 

Tel.: 0161 7284177 * FAX: 0161 7284017 
For more information on the 
products featured on these pages call 
FAX : W"; 1908) 389-8173 
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BYDICKCONKUN 


: n Editors 
Comments 


More Talent, Tools , and Tips 


W hat happened to 1994? It's hard to be¬ 
lieve that another year is already start¬ 
ing. This is an appropriate time to wel¬ 
come two new additions to OS/2 Developer: 
Peter Westerman and Guy Scharf. 

Peter is our new Publisher, replacing the irre¬ 
placeable Cathy Passage. Peter comes to us from 
Microsoft Systems Journal, of all places, where he 
will still maintain the duties of publisher. Mathe- 
i patted completes his triad of magazines. Welcome 
to the other side, Peter! 

Guy is another welcome addition to our pages. 
We have been without a software tools reviewer; 
now that slot is filled. Guy is no stranger to OS/2 
programming. He's the sysop of the OS/2 Ven¬ 
dor and OS/2 Shareware forums on CompuServe. 
He is also the cofounder, treasurer, and newsletter 
editor for the OS/2 Bay Area Users Group. Guy 
will be reviewing the latest and greatest tools for 



OS/2 application development. If you have a 
favorite tool to recommend, or one that you just 
want to know more about, let Guy know. 

RACY PICTURES 

The second annual OS/2 Developer 
5K Race took place during Software 
Development '95 East, Those of you 
who participated were treated to an 
invigorating, early morning tour of 
our nation's capital. If you didn't stop 
to sightsee along the route, you just 
may have been a winner, 

TALK TO US! 

In 1995, as in 1994, we are striving to make OS/2 
Developer a publication that works for you. We 
have made some changes and plan to make more, 
but you are in the driver's seat. What kind of arti¬ 
cles do you like most? Are you seeking more 
examples, tips, and hints? Are the code listings 
helpful? Do you use the sample program files in 
our CompuServe OS2DF2 forum? Have we over¬ 
looked any topics? Are we overdoing any? Take 
a moment and e-mail us with your comments; we 
want to hear from you! 

Have a Great 1995! 




Drdt Conklin 
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Quantities are limited. 
Order now! 

For fastest service, 
fax your order to us 
at 415-905-4967. 


A Special Report 
from the 
publishers of 
OS/2 Developer! 
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I jaYES! Please send me_ copies of Smalltalk! 

Each copy is only $9.95 in the US or $12.95 in Canada. 

Please add $2.50 for shipping and handling. 

□ My check is enclosed 

□ Charge my credit card: Q Visa □ MasterCard □ American 
Express 

Name 

Signature Dale 

Send them to: 

Name 
Address 


City Stale Postal Code 

L___I 


Mail: Smalltalk 

P. O. Box 7046 
San Francisco 
CA 94120 

Phone: 1-800-444-4881 
Fax: (415) 905-4967 






















You Discovered 
the 32-Bit Power 
of OS/2. 




Introducing 


Now Master It at 
OS/2 DEVELOPMENT '95 


the conference for advanced software development ■ 



he publishers of OS/2 
Developer magazine have 
assembled industry leaders to host the first 
independent Pan-European conference on 
OS/2, You'll sharpen your OS/2 skills 
and learn from the experts about the latest 
techniques and technologies to increase 
your effectiveness on the job. 


What's included: 

M Excellent educational 
seminars 

■ Keynote speakers 

■ Product Roundtables 

■ And special events! 



You'll Learn 
More About 


■ SOM programming 

■ Workplace shell 
programming 


I User interface 
development 

I Open DOC 

Object-oriented 

programming 


REXX programming 
SmallTalk, and more! 
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Our new OS/2 Toolbox column will review products that help develop applications for the OS/2 platform. 

ByGUYSCHARF 


Product Reviewed: 
VX-REXX Client/ 
Server Edition 



Guy Scluirf 


elcome to the OS/2 Tool- 
mm mm box. in this column, 1 will 
be reviewing tools for the 
professional OS/2 developer. 1 am espe¬ 
cially interested in products that help in 
developing high-quality Presentation 
Manager applications. I'll tell you what I 
see as the strong points of each tool as 
well as point out the limits of applicabil¬ 
ity and any major warts. 


VX-REXX 

VX-REXX for OS/2 is a powerful yet 
easy-to-use visual application develop¬ 
ment tool that uses REXX as its pro¬ 
gramming language. Watcom has just 
released VX-REXX for OS/2 Version 2.1 
and a new product named VX-REXX for 
OS/2 Client/Server Edition. The 
Client/Server Edition is version 2.1 with 
database and charting functions added. 
I tested the Client/Server Edition and 
found it a pleasure to use. 

VX-REXX helps you create native 
OS/2 Presentation Manager applica¬ 
tions. The integrated development envi¬ 
ronment includes a debugger, graphical 
design tools, and drag-and-drop pro¬ 
gramming. VX-REXX supports OS/2 
Presentation Manager controls, includ¬ 
ing the spin button, container, notebook, 
value set, and slider. VX-REXX adds pic¬ 
ture radio and push-button controls. 


Timer and DDEClient objects support 
timer events and building a DDE client 
application. 

When you are creating an applica¬ 
tion, VX-REXX is in design mode. After 
you have completed the application, you 
may run it directly, without leaving the 
development environment, in either a 
run mode or a debug mode. Debug mode 
runs your program under an integrated, 
easy-to-use debugger. Once you are satis¬ 
fied with the application, you can gener¬ 
ate an executable file for distribution. 

An application in VX-REXX is 
known as a project. To build the user in¬ 
terface, you place objects on the win¬ 
dows. An object consists of properties 
and methods. An object's properties in¬ 
clude data and style settings. Methods 
are the functions the object can perform. 
For example, an entry field object has 
properties such as its value, maximum 
number of characters, color, and 
whether or not the field is readable. It 
has methods for setting the focus, get¬ 
ting and setting properties, and invok¬ 
ing help. To set the properties, you open 
the object's Properties notebook and set 
as desired. You can also set properties at 
run time by calling methods to set the 
properties dynamically. You can even 
create the objects at run time rather than 
at design time. 
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Like Presentation Manager, a VX- 
REXX application is event driven. Each 
object has a set of events it can respond 
to, such as a mouse click, entering data 
in the object, or another object being 
dropped on it. Most of the VM_C0NTR0L no¬ 
tification messages familiar to the 
Presentation Manager programmer 
show up as events. VX-REXX adds more 
events, including ones for drag-and- 
drop support and data verification. You 
define how the object is to respond to 
each event by coding an event handling 
routine. Select an event from a cascaded 
pop-up menu or from the properties 
notebook, and a section editor displays 
an edit window for your program to 
handle the event. The programming for 


handling an event is often quite short. 
REXX is an easy language to use, and 
VX-REXX takes care of the details. 
Coding event handling routines is much 
easier in VX-REXX than in C. 

Multithreading is the key to OS/2 
applications that are responsive to the 
user. VX-REXX makes multithreading 
easy—one command launches a thread. 
The thread resides in a separate code file 
and can post results back to the 
launcher. 

Figure 1 shows the event list for the 
Cancel push button on a simple win¬ 
dow. Clicking the right mouse button on 
any object pops up a context menu. The 
Events menu item cascades to a list of all 
events supported for that control. A 


EC VX-REXX -- Project (D:\VXREXX\Projects\Sample Projects Pro je { 


Project Tools Windows Run Options Help 


Object: , PB CANCEL' [PushButton] 



Figure 1 . Event list for a push button. 


JANUARY/FEBRUARY 19 9 5 
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check mark is placed beside events 
for which you have defined an 
event processing routine. 

Figure 2 shows part of the 
event routine for a Change event 
on an entry field. I wanted to dis¬ 
able the OK button if nothing had 
been entered in the entry field. 
Drag-and-drop programming 
makes this easy. If you drag an ob¬ 
ject to the edit window, a list of all 
methods and functions for that ob¬ 
ject is shown. Select the function to 
enable or disable an object and a 
dialogue appears allowing you to 
specify whether the object is to be 
enabled or disabled. The correct 
code is inserted in the edit window 
where you dropped the object. 

If you forget some REXX syn¬ 


tax or a VX-REXX function, just 
click on the right mouse button in 
the edit window, select "insert 
code...", and a list of VX-REXX 
functions as well as those of the 
REXX language itself is displayed. 
Select the one you want and the 
editor will insert the accurate and 
complete REXX statement. It's 
hard to go wrong! 

The drag-and-drop program¬ 
ming and code insertion list 
greatly simplify learning the prod¬ 
uct. The implementation is very 
smooth and allows you to use as 
much or as little of it as you like. 
You can rely on it for everything, 
for nothing, or for anything in be¬ 
tween, depending on how adept 
you are with VX-REXX. 


Version 2.1 fills in many gaps 
found in earlier versions. Here are 
a few samples from a list too long 
to include in this review. In version 
2.1, you can drag an object from 
the toolbox to the window to cre¬ 
ate a new object of that type. Only 
one step (drag) is required rather 
than the two steps (select tool, cre¬ 
ate object) required in earlier ver¬ 
sions. A Tab Editor eases changing 
the tab order of objects in a win¬ 
dow. Properties have been added 
to many objects to support most 
Presentation Manager control 
styles. Many new methods and 
properties have been added to the 
Container and MLE objects. Drag- 
and-drop events are supported on 
all objects, making it easy to sup- 


" VX-REXX -- Project (D:\VXREXX\Projects\SampteProject\Proje 


Project Tools Windows Run Options Help 


Object: 'PB.OK' [PushButton] 
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Figure 2. Enabling a push button using drag-and-drop programming. 
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port dragging and dropping 
within an application. 

If you need to handle events 
VX-REXX does not support, the 
new DefineEvent method allows you 
to define a processing event for any 
Presentation Manager message. 
This is useful for handling unfore¬ 
seen conditions or custom objects 
with their own private messages. 

VX-REXX FOR OS/2 
CLIENT/SERVER EDITION 

The VX-REXX for OS/2 Client/ 
Server Edition adds database and 
charting tools to VX-REXX version 
2.1. The database tools include two 
new objects—a connection object 
and a query object—and a 
Database Administrator utility. 
The charting tool is a new chart ob¬ 
ject that supports a wide range of 
chart types. Complete online and 
printed manuals and sample pro¬ 
grams demonstrate the varied ca¬ 
pabilities of these objects. 

The Client/Server Edition sup¬ 
ports IBM Database 2/2 (DB2/2), 
IBM DB2 on larger systems using 
DDCS/2, Watcom SQL for OS/2, 
and any ODBC-compliant data¬ 
base. For ODBC, you must obtain 
the ODBC driver for the database 
from InterSolv. 

But, wait! This is the Client/ 
Server Edition. Where is the Server 


part of the product? Despite the 
name, there is neither a VX-REXX 
server component nor support for 
building a VX-REXX server. VX- 
REXX for OS/2 Client/Server edi¬ 
tion is a tool to build client appli¬ 
cations. Any server component is 
supplied by the database system. 

I tested VX-REXX for OS/2 
Client/Server Edition using IBM 
DB2/2 and both stand-alone and 
server versions of Watcom SQL for 
OS/2. 

EASE OF USE 

How easy is the database object to 
use? One way to measure that is to 
build an application that will view, 
search, and update a simple data¬ 
base table. To build that application 
in VX-REXX Client Server Edition, 
you open the Projects folder, tear off 
a new project from the project tern- 
plate, open your new project, and 
open the VX-REXX object within it. 
VX-REXX presents you with an 
empty window. Drag a connection 
object to the window. Open the con¬ 
nection object and enter the data¬ 
base name and type (IBM DB2/2, 
Watcom SQL, or ODBC). Close the 
connection object and drag a query 
object to the window. Open the 
query object and select the table 
and columns desired. Check the 
check boxes that ask VX-REXX to 


create the fields and push buttons. 
Check a radio button to indicate 
whether you want an entry field 
per column or prefer that multiple 
records be displayed in a container. 
Close the query object, and VX- 
REXX creates all of the fields and 
push buttons needed. 

You now have a working ap¬ 
plication, and it has taken only a 
few minutes. A few more minutes 
takes care of cosmetics, such as 
adding a title bar, changing field 
captions from database field names 
to user terms, and refining the lay¬ 
out by adjusting entry field lengths 
and rearranging the push buttons. 
Figure 3 shows the result. 

The sample programs include 
more complex examples, including 
two with master-detail organization. 

Simple methods to insert and 
delete records make database pro¬ 
gramming easy. If you want to use 
SQL directly, just ask the connection 
object to execute the SQL statement. 
The connection object provides 
error codes and messages from the 
SQL statement. Converting from 
DB2/2 to Watcom SQL is easy with 
the connection object. All you have 
to do is change the database type 
and name properties. That can be 
done either at design time or dur¬ 
ing execution. 

The new chart object packs a 
lot of functionality into one object. 
You can create the basic bar, area, 
pie, ribbon, and line charts. If you 
need something different, try the 
gantt, stock, box whisker, radar, 
100% area, XY, proportional, bub¬ 
ble, or combination charts. Some of 
the charts can be displayed three 
dimensionally. More than 150 chart 
options give you detailed control 
over the appearance of the chart. A 
Chart Editor lets you control these 
options at design time. As with 
other VX-REXX objects, you can 
also create charts or change these 
options at run time. 

The chart object has events for 
clicking and double clicking. When 



Figure 3. Simple database table query and update application. 
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O^mp, 


On a typical 
day, stockbroker Bret 
Williams 
makes his 
personal 


And he gets more out of the soft ware he 
knows and uses, like Windows™ and DOS. 

Bret has OS/2 Warp, the operating system 
that offers true multitasking, Crash Protection™ 
Internet-access — not to mention a BonusPak 


computer do some very atypical things. 

He imports live market data off the ticker at 
the same 
time that he’s 
reading the 
stock page 

on-line, at the same time that his computer is 
firing off e-mail to a client, and at the same time 
that its faxing his lunch order (pizza, usually). 

He runs his PC without fear of crashing. 

(If any one of his applications ever goes down, 
everything else stays up.) 


filled with productivity applications. 

The price is also less than you ever thought 

possible: 
under $90. 
Of course, 
you’re 

welcome to do your ow n risk assessment. 

OS/2 Warp is available now; (For stock¬ 
brokers and anyone else looking for a great 
investment.) To get warped, stop by your local 
software <lealer, or call 1 800 3 IBM-OS2. 

Ask for a free demo disk. 


feu. DO A /cBASWt 

^ AVOlP * 


The new 32-bit, ^ crash-protected 

W i"'l<.wlr" aSki " ft multimcdia ’ 'ntemet-acce^^ OS/2 
nen % totally cool way to run Y° ur 


WarP 


OS/2 Warp is available from your software dealer, It Is also available from IBM for $89 by calling 1800 3IBM-QS2. 

Resells* prices may vary. OS/2 Warp consists od OS/2 Version 3 and EfonusPak IBM, Operating System/2 and OS/2 ate registered trademarks ol ine 
IntetnalionaJ Business Machines Corporation Crasd Ptotedion and me OS/2 logo are trademarks oMBM. Windows is a trademark ol Microsoft Corporation, 
©1994 IBM Carp. 
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Figure 4. Pie chart in three dimensions. 


you receive such a mouse event, 
you can ask which row and col¬ 
umn was clicked on. This makes it 
easy to implement a ''drill-down" 
chart, where clicking on one part 
of the chart will explode the chart 
into more detail. The chart object 
can also be bound to a query ob¬ 
ject. This gives you a chart display 
of data from a database with al¬ 
most no programming required. 

Eleven sample chart programs 
are supplied, including two in 
which the chart is bound to a 
query object and one that demon¬ 
strates a drill-down application. 
Figure 4 shows a three-dimen¬ 
sional pie chart that is typical of 
the charts you can produce with 
the chart object. 

DOCUMENTATION 

The Client/Server edition includes 
two books: the Programmers Guide 
and Reference and the Client/Server 
Edition Objects Guide. The first 
book is common to both VX-REXX 
2.1 and the Client/Server edition. 
The Programmer's Guide includes a 


tutorial on creating a simple appli¬ 
cation. It describes the structure of 
a VX-REXX project and has sec¬ 
tions addressing common pro¬ 
gramming topics, such as using 
multiple threads, modeless win¬ 
dows, debugging, controlling, 
other processes, and creating ob¬ 
jects at run time. 

The reference section lacks the 
detailed descriptions found in the 
version 2.0 manuals. With this new 
version, Watcom has reduced a 
450-page reference to a 25-page al¬ 
phabetical list of objects, proper¬ 
ties, events, methods, predefined 
routines, and functions. While 
everything in the books is avail¬ 
able online in an .INF file, I find it 
impossible to really learn a tool 
from online documentation. To be¬ 
come expert, I find I have to read 
reference manuals from cover to 
cover until I understand it all. You 
won't want to discard your old 
VX-REXX 2.0 manual! 

The Client/Server Edition Ob¬ 
jects Guide contains two sections 
describing the features of the VX- 


REXX Client/Server Edition be¬ 
yond those included in the base 
VX-REXX version 2.1: the Database 
Objects Guide and the Chart 
Object Guide. Each guide has tuto¬ 
rial, programmer's guide, and ref¬ 
erence sections. In this book, the 
reference sections include com¬ 
plete descriptions and not just lists. 

All of the books are available 
online as .INF files that use hyper¬ 
links well. The information is orga¬ 
nized in additional ways to the 
printed presentation. For example, 
the online reference shows the 
events, properties, and methods 
available for each type of object. 
The online documents are a plea¬ 
sure to use. 

WARTS AND BLEMISHES 

The base components of VX-REXX 
2.1 have been honed over several 
releases and operate very smooth¬ 
ly. The database tools of the 
Client/Server Edition are new and 
do have rough edges, primarily in 
the design environment. I was able 
to work around problem areas eas¬ 
ily though. The Database Admin¬ 
istrator tool is another story. It had 
serious enough flaws that I was 
unable to use it to define a data¬ 
base. Fortunately, this tool is a 
nicety and not essential. 

Watcom released a version 2.1a 
patch after this review was com¬ 
pleted. This patch corrects prob¬ 
lems in version 2.1 and problems 
related to OS/2 Warp 3. I checked 
the problems I had found, and they 
were corrected. The 2.1a patch is 
available in the Watcom forum on 
CompuServe. 

LIMITS OF APPLICABILITY 

While VX-REXX does provide a 
Presentation Manager printer se¬ 
lection dialogue to make selecting 
the printer easy. Presentation 
Manager printing is not provided. 
To print, you write a report to a 
file, including printer-specific con¬ 
trol codes if desired, then print the 
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file using a VRPrintFile function. 
The chart object includes a method 
to print a chart, but VX-REXX does 
not provide a way to combine a 
chart with other printed output. 

VX-REXX provides an un¬ 
adorned entry field. More complex 
entry fields for dates, zip codes, 
and other formats are available 
from third-party vendors as add-on 
components. Watcom also has an 
Object Development Kit available 
so you can develop your own cus¬ 
tom objects to use in VX-REXX pro¬ 
jects. VX-REXX does not support 
drawing directly on a window; you 
would need to develop your own 
object to access a window directly. 
Also, VX-REXX does not support 
every last feature of OS/2 
Presentation Manager, such as the 
owner draw style. The ease of use 
and rapid development more than 
made up for any small features that 
were missing in my use. In writing 
a small business application, VX- 
REXX supported all of the OS/2 
Presentation Manager features I 
needed and many more besides. 

REXX is not C, and with this 
distinction come both advantages 
and disadvantages. It may be diffi¬ 
cult to work with some data types 
and structures, as REXX has only 
strings and integers. Using C and 
Presentation Manager, you can cre¬ 
ate subclasses and superclasses to 
alter the behavior of objects. This 
will be harder to do in REXX. An 
interpreted language such as REXX 
is likely to be slower than C in some 
situations, such as loading a con¬ 
tainer with thousands of records. 

Applications developed in VX- 
REXX can be distributed as EXE 
files. Some Watcom DLL files are 


required; they may be distributed 
without royalty payment. The 
VROBJ.DLL file has grown to 893K 
in this release; database and chart¬ 
ing DLLs and related files are 
about 200K and 350K, respectively, 
depending on the database to be 
supported. 

TECHNICAL SUPPORT 

Watcom offers technical support 
by telephone, fax, BBS, Internet, 
and CompuServe (GO WATCOM). 
A fax response system provides 
technical information. I called 
Watcom twice and found the staff 
to be courteous and knowledge¬ 
able. I was quickly passed on to a 
specialist for a more complex ques¬ 
tion. I posted several questions on 
the Watcom forum on Compu¬ 
Serve. How-to questions were gen¬ 
erally answered overnight; more 
difficult questions requiring re¬ 
search took longer. The Watcom 
staff was very receptive to problem 
reports and very honest about 
problems and workarounds. I 


found this response refreshing; it 
gave me confidence that I would 
get real answers to my questions. 


£ 


SUMMARY 

VX-REXX is excellent for develop¬ 
ing OS/2 Presentation Manager 
applications quickly. The drag- 
and-drop programming interface 
makes learning VX-REXX and 
REXX easy. All OS/2 controls are 
supported, and custom controls 
can be added, allowing the devel¬ 
oper great flexibility in designing 
the application. The Client/Server 
Edition makes using an SQL data¬ 
base easy. I will definitely keep the 
VX-REXX Client/Server Edition in 
my toolbox. 

Guy Scharf is president of Software 
Architects Inc., a software development 
firm specializing in developing OS/2 
Presentation Manager applications for 
vendors and business. He can be reached 
via e-mail at 76702.557@compuserve.com 
or at Software Architects Inc., 2163 Jardin 
Drive, Mountain View, Calif. 94040. 


PRODUCT INFORMATION 

Watcom VX-REXX for OS/2 Client/Server Edition.$299 

Watcom VX-REXX for OS/2 Version 2.1 Standard Edition.$99 

Upgrade pricing; 

From earlier version to 2.1.$59 

From earlier version to Client/Server Edition .$199 

Vendor: Watcom International Corp. (subsidiary of Powersoft Corp.) 
415 Phillip St. 

Waterloo, Ont. N2L 3X2 
Tel. (519) 886-3700 
Fax. (519) 747-4971 
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Keeping with the theme of the issue, a mystical area of programming, the exception handier, is 
demystified. By MARK BENGE and MATT SMITH 


An Exception You 
Can Handle 



Matt Smith 


A ff ot so long ago, in a place 
Ilf nearby (hey. Star Wars is in 
* » production again, just getting 
ready, sort of), a demo was being 
waged. Wonderful screens of dialogues 
and windows were being dutifully dis¬ 
played to wonderment of all. Everyone 
was being mesmerized by this show of 
power and majesty. Splat! Wait a 
minute, that wasn't part of the script. 
While looking for a quick exit from 
this major embarrassment, it was no¬ 
ticed that the audience was moving in 
closer, trying to get a look at the display 
They were doing this while saying to 
each other that they had to know how it 
was done. 

Hold it, did they just ask how it 
went splat? Nope. They wanted to know 
how the exception handler was done 
such that the exception dialogue re¬ 
ported the function where the applica¬ 
tion tripped over itself. 


GRACEFULLY EXITING STAGE LEFT 

Interesting, that. Having a major faux 
pas and being able to walk away virtu¬ 
ally unscathed. Why? Quite simply by 
having a graceful exception handler that 
told the user what was happening and 
providing us, the writers of the applica¬ 
tion, with a nice report of where things 
went wrong. 


Unfortunately, almost all the major 
compiler writers just don't get it that 
OS/2 has a really neat exception han¬ 
dler that with a little thought could pro¬ 
duce useful diagnostic information and 
should be part of the compiler they sell. 

Now, you may be asking, why 
would we want to talk about it and not 
keep this as one of the trade secrets or 
crown jewels? We want to challenge 
those compiler writers into providing 
support for this issue. We will show you 
why in a moment. 

YUCm THEORY TIME 

Okay, kids, put on your theory propeller 
caps and follow the discussion on the 
chalkboard. The problem: OS/2 catches 
our program doing something stupid 
and tells our exception handier where it 
occurred. Great, let's just print out the 
address and call it a day! 

Yeah, right. That's exactly what 
most of the compiler exception handlers 
do if they handle the exception at all. We 
still don't know where the program shot 
itself in the foot though. 

Well, maybe we should use Method l: 
the good oT linker map, which is the 
method that we have all used for years 
and years. Unfortunately, it really is 
only useful in telling us sort of, maybe, 
kind of, somewhat where the problem 
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occurred. This is due to the fact 
that the link map shows only the 
addresses for the global functions 
and not for any statics, it is also 
difficult to try to locate the prob¬ 
lem if the address is outside the 
main application address space, 
such as within a system call or 
within a DLL you have called. 

The method we will show. 
Method II, borrows heavily from 
the link map concept but without 
paperwork. Here we rely on tables 
of tables. Huh?? 

Okay, the concept is really 
quite simple; it is just the imple¬ 
mentation that gets a wee bit 
messy and tedious. Consider that 
the exception address is within 
your main application space. By 
main application space, we mean 
your source from the first module 
up to the last module, as illus¬ 
trated in Figure 1. Following this 


last module usually is the start of 
the compiler run-time library. By 
rights, it is part of your address 
space, but since we don't know its 
address or function address, we 
treat it as being outside our ad¬ 
dress space like that of the system. 

Each of your functions follow 
one another, maybe in the order you 
coded or in some other order the 
compiler and linker have put to¬ 
gether. The only thing we need to do 
is find out between which two func¬ 
tions the exception occurred. Then 
we know where we tripped up. 
That's it. It is as simple as that. The 
idea even works with your DLLs. 

Method III is where the com¬ 
piler writers are needed and 
should take note. Using Method II, 
where the module and function are 
reported, you should also have the 
source line reported. Now that 
would be truly wonderful. 


ACTUAL DESIGN 

The real trick to making most of 
this work is the building of a table 
within each source module that 
records the function address along 
with the name of the function. Then 
in the exception handler of the ap¬ 
plication, a different table is built 
that references each of the tables 
within each of the different mod¬ 
ules. Like we said, tables of tables. 

When an exception occurs that 
is handled by our exception han¬ 
dler, we sort the tables so they are 
in ascending order and then walk 
them, trying to find the two func¬ 
tions in between which the excep¬ 
tion falls. Once found, we know 
exactly where we died. This works 
great, especially when you have 
your software being used halfway 
around the world and it can tell 
you exactly where it is feeling sick. 
Only if it were truly this simple! 

What do you do when there is 
the possibility of the exception oc¬ 
curring within a DLL? Well, first 
you check to see if the exception 
falls within your source code ad¬ 
dress space, namely from the start 
of the application to the exception 
handler, which we have caused to 
be at the end. If it isn't in this 
space, we call the exception lookup 
handlers within each of our DLLs 
to see if the exception occurred in 
one of them. 

If none of them reports owning 
the naughty code, we then use our 
next death-defying act (at times, as 
we will show in a moment, this is 
exactly how we have coined it). 
Here we walk the stack with the 
idea that we will trace back 
through to our address space. 
Then we state that the function 
was the starting point of the stack 
trace. At least this gives us an idea 
of where to start looking. 

And, if all else fails, like when 
the stack is a mixture of 32-bit and 
16-bit addresses, we stick our 
heads in the sand just like the com¬ 
piler writers do. 


main( ) 

Excepti on 

Address 

ExceptHandler( ) 


Module 1 


Module 2 


Module 3 


Run-Time 

Library 


Known 

Address 

Space 


DLL 


Figure 1 . Main application space 


18 


OS/2 DEVELOPER 
















THE IMPLEMENTATION 

In the sample source code, which 
can be found lurking in the usual 
electronic hangouts, we have a 
bunch of modules with some stu¬ 
pid, do-nothing functions that, de¬ 
pending on the alignment of the 
planets, will decide to GR 

Within each is a table that is 
declared statically. This table is 
then referenced by a structure, IN¬ 
TERNAL ADDRESS that contains the mod¬ 
ule name and the table address. 

Then, within the XCept.C mod¬ 
ule is an array of the INTERNAL ADDRESS 
structures from each of the mod¬ 
ules. This is the backbone of our 
lookup scheme. 

Inside our exception handler, 
we place the smarts to sort the ta¬ 
bles and call a routine that will do 
the actual lookup. If the address 
isn't found within the lookup ta¬ 
bles or any DLL's, we use the re¬ 
turned BP register to start the walk 
back through the stack. 

Now, this walk on the wild 


side of the stack can be tricky. First, 
you have to be careful that the 
value you see is a 32-bit value and 
not a 16-bit return address. 

This is done by checking the 
address against the stack limit. If it 
is outside it, it is probably a 16-bit 
address. Next, and there is no 
check on this, if the compiler wee¬ 
nies have decided to party on the 
BP register by using it as a general- 
purpose register, you are most def¬ 
initely out of luck. Carefully check 
your compiler documentation 
since some of these compilers 
don't explain very well in their 
documentation what happens 
when they use the BP register for 
anything but the stack frame. 

Once we have traced back into 
our address space through the 
stack, we are essentially done. We 
just have to look up the traced 
back address within our tables. 

Now, it is a matter of reporting 
the damage. Here we do it in two 
places: a log file that we append 


each time an exception occurs and 
the exception dialogue shown in 
Figure 2. 



A LATE CHRISTMAS PRESENT 

One of the really neat things about 
OS/2 is that if you provide the 
proper code, you can recover 
gracefully from a full-stop excep¬ 
tion and continue using your ap¬ 
plication. A good example would 
be a conversion filter. Here, you 
would design it so any memory 
being used is not intermixed with 
the main application. Therefore, if 
things decide to fall apart, your 
main data is still in one piece. 

The best way to do this is to 
place the filter within a dynami¬ 
cally loaded DLL. just as soon as 
the function in the DLL is called, 
you register an exception handler 
within the DLL. This exception 
handler is now at the top of the 
chain, which means it gets called 
first Next, you do a setjmp call, so if 
an exception occurs, you can 



Figure 2 . Exception dialogue* 
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gracefully recover and report it to 
the user. 

The DLL exception handler in 
this case can be like the full-blown 
one. Instead of stating it is fatal, 
however, state it is recoverable. 
Then perform a longjmp back to the 
location where you did the setjmp 
and unwind the DLL exception 
handler before returning to the 
main application. 

We want to caution you here. 
You have to be careful with this and 
have clearly thought through your 
design of both the DLL and your 
data. You should really only use 
this if you can separate your appli¬ 
cation data from that of the DLL. 


MAKING IT ALL WORK 

To make this work with a much 
larger application, you must update 
the tables by hand each time you 
add or remove a function. This up¬ 
dating of the tables is why we men¬ 
tioned earlier the tedious nature of 
the exception handler. Hence our 
endearment with the compiler writ¬ 
ers. The compilers can easily and 
dynamically update these tables for 
us. They will ensure that they have 


all of the functions defined, 
whereas we may make a mistake if 
we are not diligent. 

The same problem occurs 
when we add a new module. We 
need to create a new entry within 
the internal address array after we 
have created the table within the 
new module. 

But this work will be worth it 
when you get your first support 
call from some pub in Edinburgh 
and you know exactly where to 
look within your application. 

Mark Benge. IBM Software Solutions , 
Cary, N.C., is a staff programmer who 
joined IBM in 1989 and has worked on 
various CUA 1 91 controls for OS/2 2.x, He 
works in IBM user interface class library 
development where he was involved in 
the implementation of C++ classes for 
drag and drop in C Set++ 2.1 Mark has a 
B S. in computer science from Western 
Carolina University. He can be reached on 
CompuServe at 73532,2063 and on 
Internet at banzai@vnetibm.com. 

Matt Smith, Prominare Inc ., Toronto f 
Ontis lead architect for the Prominare 
Development System, an OS/2 2.x 


advanced GUI development environment 
Matt has been actively involved with 
OS/2 since 1988 and cofounded 
Prominare in 1990l Smith has a degree in 
architecture from the University of 
Waterloo . He can be reached on Internet 
at msmith@interlog.com. 
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Credits: Screen captures were 
done through OpenShutter from 
One UP Corp, and touched up 
through PaintBrush in Win-OS/2. 

You can download XCEPTN.EXE 
from these electronic sources: 

CompuServe's OS2DF2 forum 
(OS/2 Developer Mag section). 

File Area 11 on the IBM PCC 
BBS, (919) 517-0001. 

OS/2 Tools section on the OS/2 
BBS for IBM TALKLink 
customers. 

FTP to the site address gold .inter¬ 
log,com and log in as anony¬ 
mous. The source is located in the 
/pub/protninare subdirectory. 
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WHEN I WANT ADVICE ABOUT OBJECT-ORIENTED 
PROGRAMMING, I’LL ASK AN EXPERT. 



SO, ASK US. 


You already Know reusable class libraries promise a 
dramatic increase in productivity and efficiency for 
professional application developers. You also know class 
libraries created with one C++ compiler can't link with code 
created by another C++ compiler. And that libraries written 
in one language can't be used with client code written in 
another language. 

But here T s something you might not know: MetaWare and 
IBM are changing all that. 


Pretty amazing, right? And right now, you think this is where 
our pitch to sell you a compiler comes in. But you’re wrong. 

Information Only. And It's Free. We know what you 
really want is information. That way you can make up your 
own mind about the benefits of SOM and the DirectToSOM 
High C/C++ compiler for OS/2. We've prepared a white 
paper that will help. It’s called Truly Reusable Objects 
Directly From C++: How to Create and Distribute Them. It’s 
yours just for the asking. 


But with IBM's System Object Model (SOM) 
and MetaWare's High C/C++ DirectToSOM 
compiler for OS/2, developers can break that 
tight binary coupling and extend the 
advantages of procedure libraries to 
object-oriented technology. 


Out With The Old. In With The New. The tight binary 
coupling that exists between object-oriented class libraries 
and client code means that changes to either—no matter 
how small—require a complete recompilation not only of 
the class itself, but of all the client modules 
as well. 


To receive your free information, call, fax, or e-mail 
MetaWare at the numbers shown below. Once you review 
the facts for yourself, you'll understand why MetaWare and 
IBM mean “objects made easy," 



CALL 408 429 6382 
FAX 408 429 9273 
OR 

e-mail techsales@metaware.com 

FOR VOOR FREE COPY. 

TODAY. 


MetaWare 

OBJECTS MADE EASY. 
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Programming Insider 

Often some of the simplest ideas yield the greatest benefits. This issue's Programming Insider shows 
you how aliasing functions can give your applications more speed in less space. By DAVID REICH 


An API by Any 
Other Name... 



David Reich 


his issue, 1 want to discuss an 
m important but usually unknown 

™ or overlooked aspect of applica¬ 

tion performance tuning: the subject of 
calling APIs in DLLs, whether they be 
your own DLLs or system service DLLs. 
Depending on your intended use of 
functions that reside in DLLs, you have 
many options in how to call and use 
them. There are also obvious perfor¬ 
mance impacts if you call an API by 
name, having it preloaded and fixed up 
when you call the function, or if you 
load the module when you need it and 
fix up the reference at run time. There 
are also impacts in calling a single func¬ 
tion, or sets of functions, all over your 
code. Let's first look at how DLLs work. 


UNKING DYNAMICALLY 

Like static run-time libraries, a DLL is a 
library of functions that can be used by 
many programs. However, the functions 
in DLLs are not bound to executable 
programs. The functions remain in the 
DLLs, which are loaded by the OS/2 
program loader and are callable by pro¬ 
grams written to access their functions. 

A statically linked library is a .LIB 
file, bound to an executable. A DLL con¬ 
sists of the DLL, which contains the rou¬ 
tines, and a .LIB file, which is the "road 
map" to the DLL. When you build an 


application and link with a DLL's .LIB 
file, the linker places not the routine (as 
it would with a statically linked library) 
but an external reference record that 
points to the DLL and a function num¬ 
ber (the ordinal of the function) within 
the DLL into the object code. 

If you were to peek inside your exe¬ 
cutable program file, you would see that 
in the CALL instructions for all of the DLL 
reference records, there is just a refer¬ 
ence to an external function. More im¬ 
portantly, if you were to look at the EXE 
header (you can, with the tool EXEHDR, 
which is part of the compiler and 
toolkit), you would see there are refer¬ 
ences to DLLs and ordinals, such as 
PHtfBl.139. This indicates that the function 
at ordinal 139 (the 139th function) in 
PMtflOLL is the one being referenced. 

This list of DLL ordinals or imports 
(referencing a DLL's function by name is 
also called importing the function) in 
the EXE header is called the import list. 
Whenever an OS/2 program is loaded, 
the program loader examines the import 
list and fixes up the references to the 
DLLs. This causes the DLL to be loaded 
for the reference to be fixed up. This is 
not a terrible thing when calling system 
services since most of the system DLLs 
are already loaded. Also, the fix-up is 
much faster than if you were using 
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You don’t need weird hair 
to form a powerful peer group 


Announcing LANtastic* for OS/2 


Guilty of going to extremes to win peer-to-peer connectivity 
for your team? Then consider LANtastic for OS/2, a true 52- 
bit multitasking, multithreaded peer-to-peer network operat¬ 
ing system utilizing 0S/2 r s superior power and performance. 

LANtastic for OS/2 coexists with Novell® NetWare 
Requester™for OS/2 and IBM* LAN Server clients and easily 


communicates with LAN Server, Windows NT™and other 
SMB-based servers. It has centralized network management 
and flexible security options that are easy to use. 

Still need more proof? Call 1-800-8091239 for the 
Artisoft Premier"* or Artisoft Advantage 5 * Partner nearest you. 
Then judge for yourself. 


ARTISOFT 
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your own DLL since the loader 
would have to load and then re¬ 
solve these addresses. This de¬ 
scription applies when you import 
a function by name, such as calling 
VinCreatetfindow or DosSleep. 

It is also possible to call func¬ 
tions in DLLs by address. After all, 
DLLs are shared code. Your pro¬ 
gram can gain addressability to the 
code in the DLL through importing 
by name or by calling DosLoadModule. 
Once you have a handle to a DLL 
module, you have addressability to 
the module. Simply stated, address¬ 
ability means that you can call a 
function in its address space with¬ 
out taking protection exceptions. 

When you call DosLoadModule, 
you are given a module handle. 
The other part to calling a DLL 
function is to get the address of the 
function you want. You do this by 
calling DosQueryProcAddr. This func¬ 
tion takes the DLL handle, the 
module name or ordinal, and gives 
you the 32-bit address of the func¬ 
tion you want. You can then call 
the function, as shown in Figure 1. 

YouTl notice that the function 
call does not involve importing the 
function by name, and as such, 
there is no entry for the function in 
the EXE header You may wonder 
where I'm heading with all this. 


FIXING UP AND ALIASES 

As you've just seen, whenever you 
call a function in a DLL by name, 
you import the name and it stays 
in the imports table in the EXE 
header. For every reference in the 
code to one of these imports, there 
is a fix-up in the application 
process's swappable memory. Not 
only are fix-ups performed when 
the application loads, slowing ap¬ 
plication load performance, they 
are also stored in application- 


swappable memory, increasing the 
working set size of the application. 

You could eliminate the fix-ups 
in application-swappable memory 
by calling the functions by address, 
but that is a bit more inconvenient, 
both in the amount of code you 
have to write and in the inherent 
parameter checking you get when 
calling the APIs. (The compiler 
checks the code against the function 
prototypes to give you parameter 
checking, whereas when calling by 
function pointer, as in Figure 1, you 
get no parameter checking.) Aside 
from the inconvenience, you'll have 
OosLoadHodule and DosQueryProcAddr 
calls in many places in the code 
where you would not otherwise, 
wiping out the memory savings 
you'd gain by calling by address. 

You can eliminate much of this 
overhead and keep the advantage 
of compile-time parameter check¬ 
ing with a simple technique I call 
'"aliasing" APIs. That is, just call 
the API by another name. 

Let's look at the difference be¬ 
tween a DLL function call, which 
we've been discussing, and a call 
to an internal function of the appli¬ 
cation. DLL function calls have ex¬ 
ternal reference records in the code 
of your application. In the 16-bit 
world, these would have been far 
calls. In the 32-bit world, these are 
simply near calls since the entire 
system is one 32-bit flat address 
space. An internal function call is 
also a near call. The biggest differ¬ 
ence, and the one in which we are 
interested for this discussion, is the 
overhead inside your application 
to store all of the fix-ups for exter¬ 
nal, or DLL, function calls. Internal 
function calls need no fix-ups. If 
you can call system services with 
internal function calls, you reduce 
the need for these fix-ups. 



Figure 1 . Calling a DLL function by address . 


If you have many places in 
your application where you call, 
say, DosBeep, you will have a fix-up 
for every call. Why not just write 
one small function in your applica¬ 
tion, called MyOosBeep, which takes 
the same parameters as DosBeep? 
Inside Wy DosBeep, you simply call the 
real system service DosBeep with the 
same parameters as DosBeep taken 
from the parameters passed to 
MyDosBeep. This may seem an inordi¬ 
nate amount of overhead to save a 
few bytes here and there, but de¬ 
pending on how often you use a 
system API, you can save a consid¬ 
erable amount of memory. 

This simple technique not only 
saves you memory when you need 
to call system services but also can 
help you structure your own code 
to make it easier to maintain and 
enhance. For example, writing 
your own "wrapper" functions to 
encapsulate calls to the OS/2 
memory management APIs allows 
you to track the memory function 
calls in your application better. 
Rather than have to trace OS/2 
memory management API func¬ 
tion calls all over your code, you 
have a central point to watch. 

This aliasing of DLL functions 
is not restricted to system service 
DLLs, but it can be used for any 
DLL. By using this simple tech¬ 
nique, you can lower the working 
set size of your application while 
making debugging easier. Some¬ 
times the things that give you ben¬ 
efits like this are the simplest and 
most often overlooked. 

David Reich has been with the IBM OS/2 
development team since 1987. He has 
worked on many parts of the system, sup¬ 
ported customers and application develop¬ 
ers, and traveled the world giving semi¬ 
nars and teaching OS/2. He is currently 
working on the second edition of t 
Designing OS/2 Applications, published by 
John Wiley & Sons . He can be reached on 
CompuServe at 78711,632 or via Internet 
at speedracer@vneLibm.com. 
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OS/2 Programming 
Shouldn’t Have to Hurt. 



Introducing VisPro/C and VisPro/C++, 
easy-to-use tools for IBM C Set and C Set ++ 
that aren’t hard on your wallet. 


Other tools allow you to build robust, 32-bit 
OS/2 applications, but they also require 
more of your time and money. VisPro/C™ 
and VisPro/C++™ give you complete drag 
and drop visual programming, with all of the 
bells and whisdes - without having to reach 
deep into your pockets. 

Bells and Whistles 

VisPro/C and VisPro/C++ pack an 
unbelievable amount of functionality into a 
box. You get a Workplace Shell-enabled GUI 
environment that fully supports the IBM 
C Set compilers and User Interface Class 
Library. Both products have the most CUA *91 
objects from simple buttons to 3-D business 
graphics and everything in between. 


And if that isn’t enough, we’ve included a 
visual DB2/2 database designer that allows 
you to create embedded SQL client/server 
applications or reverse-engineer existing 
DB2/2 databases. 

From One World-Class Tool 
Comes Two More 

VisPro/C and VisPro/C++ follow’ in the 
footsteps of VIsPro/REXX, the pioneer visual 
REXX programming tool. Thousands of 
customers id ready rely on VisPro/REXX for 
powerful OS/2 development. 

Now we provide the same renowned 
functionality for the C and C++ languages. 
At the same easy-on-your-vvallet prices. 


See it to believe it! 

Buy now and take advantage of our no risk, 
60-day money back guarantee. 

VisPro/C or VisPro/C++ . . $ 399 


Development Suite .*599 

All Three Products: 

VisPro/Rexx Gold, VisPro/C, VisPro/C++ 

Competitive Upgrade . $ 199 


Upgrade any visual programming tool to 
VisPro/C or VisPro/C++ 

HockWare Incorporated 
P.0. Box 336 
Cary. NC 27512-0336 
919-380-0616 
919-380-0757 FAX 
Go Hock Ware on CompuServe 
hockware@vnet.net on Internet 


Hock. 

v/are 

Pulling Vi*w in ( nnlml 


HockWare, VisPro/C, VisPro/C+ + and VisPro/REXX arc trademarks of Hockware Incorporated. All other company, product and brand names are trademarks and/or registered trademarks of their respective 

holders and are mentioned for reference purposes only. © 1 994 HockWare Incorporated. Ml rights reserved 
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The use of advanced technology, such as IBM's OS/2 platform, has changed the methods and practices 
associated with testing applications. The introduction of robotic testing has answered many of the 
challenges associated with this new technology. By JOSEPH P. BUSA 


Advanced Technology 
Needs Advanced 
Testing 



Joseph R Busa 


mm s part of a continuous quality- 
improvement effort in corporate 
* ■ systems at Empire Blue Cross 
and Blue Shield, the introduction of ad¬ 
vanced technology has caused a benefi¬ 
cial chain reaction in the project life 
cycle. Information systems is the nu¬ 
cleus that has to interface with all facets 
of our business. It is the hub of the 
wheel, with spokes that reach out into 
claims operations, membership services, 
and financial and other decision-making 
aspects of the corporation. 

Introduction of new programming 
technology, such as the OS/2 platform, 
has created challenges for traditional 
testing methods. We can no longer ex¬ 
pect to test these applications using 
methods of old. Whereas traditional 
mainframe systems may have a strictly 
defined path to follow to accomplish a 
task, graphical interface technology has 
exploded the possibilities and paths to 
take. A narrowly defined testing sce¬ 
nario may have been acceptable yester¬ 
day, but a wider scope is required today. 

The realization that a wider scope 
has to be tested and that the personal 
computer platform is being used makes 
it clear that a new way of thinking has 
to take place. Customers are becoming 
more aware that they are in the driver's 
seat. They are expecting quality prod¬ 


ucts so they can satisfy their customers' 
requirements. 

THE FRONT LINE 

Empire is the largest health insurance 
business in the country. We handle in 
the neighborhood of 100,000 claims and 
inquiries per day The complexity of 
processing, the variety of products of¬ 
fered, and the numerous business rela¬ 
tionships with health care professionals 
all come together in our data processing 
systems. With increasing competition in 
the health care market, our internal cus¬ 
tomers, claims examiners, and customer 
services representatives recognize and 
require many levels of independent test¬ 
ing of their products before they accep¬ 
tance test it themselves. 

The many features that OS/2 offers 
to the developer, such as drop-down 
menus, scroll bars, and profiling capabil¬ 
ity can make processing more efficient 
and easy to perform. These features cre¬ 
ate customer satisfaction. They give the 
application real value but cause sizable 
challenges to the testing community 
Multitasking is a good example of a fea¬ 
ture that truly creates value in an applica¬ 
tion but is rather complex for testers. The 
testing staff on the front line requires an 
understanding of these functionalities to 
test the application effectively. 
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Transitioning to Smalltalk technology? 
Introducing Smalltalk to your organization? 



The Object People Inc. 509-885 Mcadowlands Dr., Ottawa, Ontario, K2C 3N2 
Telephone: (613) 225-8812 FAX: (613) 225-5943 


SmaHtalk/V is a registered trademark of Digitalk, Inc. 
Visual Works is a trademark of Parc Place Systems Inc. 


Visual Age and IBM Smalltalk are registered trademarks of IBM. 

ENVY is a registered trademark of OTI Inc, 
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PLANNING AND TESTING METHODS 

One of the most important aspects 
of our testing is planning. Our com¬ 
pany is fortunate to have developed 
a project life cycle methodology, and 
it is used in the development of new 
systems, applications, and projects. 
This methodology calls for involve- 
ment of testing personnel in the re¬ 
quirements phase. 


Test scenarios can be designed 
as requirements are stipulated. 
Testers get involved early in the 
development process, giving them 
more time and a better under¬ 
standing of what needs to be 
tested. Well-trained testing ana¬ 
lysts are critical to the success of 
testing. Organization of data, such 
as the use of a matrix format, is 


one way to document the arrange¬ 
ment of criteria for testing. Each 
scenario that is created is a box on 
the matrix. In our case, we inven¬ 
tory the scenario so it may be used 
again depending on what type of 
testing we are planning to per¬ 
form. This is especially useful for 
regression testing. 

The execution of test scenarios 
in a complex environment is an¬ 
other critical aspect of testing that 
new, advanced technology has im¬ 
proved for us. Performing a field- 
by-field comparison of data, espe¬ 
cially attempting to cover all the 
possible paths that can be taken in 
an OS/2 environment, has taken 
us weeks in the past. The intro¬ 
duction of robotic testing tools has 
answered the challenge of these 
new technological platforms and 
significantly reduced the effort. A 
test that took a week before is 
now accomplished in a day. 
Automated Testing can be used in 
multiple ways, and new auto¬ 
mated testing strategies are being 
formulated by our test team on a 
regular basis. Vendors of this tech¬ 
nology have been particularly 
helpful in assisting with the de¬ 
velopment of new approaches and 
in networking us with other cus¬ 
tomers for idea sharing, 

OUB AUTOMATED TESTING FACILITY 

After evaluating some of the in¬ 
dustry's automated testing tools, 
such as Sterling's TestPro and 
Sequel Corp.'s ProTerm, we de¬ 
cided on Softbridge's ATF product 
since it happened to fit the needs 
of our operation. ATF is one of the 
few testing products we have 
found that can operate on multiple 
platforms, including OS/2, This fa¬ 
cility has two major components: 
the executive and the agent (as il¬ 
lustrated in Figure 1). The execu¬ 
tive directs the activity of test 
workstations or agents and con¬ 
tains the editing facility to develop 
the instructional script. The execu- 



Figure h Executive station connected to multiple agent stations, independent tests can 
be run on each agent. 
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tive acts as a command center from 
which testers can control and 
watch the execution of complex 
test scenarios* ATF has a sense of 
time and can also operate unat¬ 
tended* We plan on connecting as 
many as 50 workstation agents to 
one executive, giving us many op¬ 
tions for testing. Throughput of 
data can be greatly enhanced by 
giving 20 stations 50 test scenarios 
each instead of using 1,000 scenar¬ 
ios at one station. A configuration 
of 50 agents can also be used to 
simulate production environments 
and to execute stress testing. 

The core of the facility is the 
Distributed Test Language (DTL). 
This coding language allows users 
to perform any functionality they 
could normally do if they were sit¬ 
ting at the workstation them¬ 
selves—and more. Mouse move¬ 


ments, button selection, and key¬ 
strokes are all supported. 

Users also have the ability to 
reboot the agent from the execu¬ 
tive station. This can be convenient 
when certain error conditions are 
encountered during the execution 
of a script. Users can also use it to 
log the execution of script com¬ 
mands, allowing them to see re¬ 
sults of the tests. One of the big 
problems with testing graphical 
user interface types of applications 
is reexecuting a test on a newer re¬ 
lease of OS/2 or an application 
where the graphical windows have 
been changed ever so slightly—po¬ 
sitional changes, for example. ATF 
has the ability to recognize graphi¬ 
cal differences and, in most cases, 
permits scripts to run without 
change. Other features such as 
bitmap snaps and text snaps of the 


screen, window, or area can be in¬ 
valuable in the development and 
debugging process* 

PRACTICAL APPLICATION 

At Empire, one of the first testing 
procedures we applied this tech¬ 
nology to was performance testing, 
ATF can accurately capture, to the 
second, response times of an appli¬ 
cation. With over 200 separate tim¬ 
ings, this is impractical and nearly 
impossible for human testers* 

We've established a procedure 
where each time a new release of 
software comes to the testing area, 
it is performance tested. That data 
is put to a database and then graph¬ 
ically displayed to show the ongo¬ 
ing history. For example, in our 
document imaging environment, 
performance tests on image re¬ 
trieval times were developed and 


Point and dick your way to fast development 
of GUI client-server applications. 


flit till CykxM Omfltf Htrtp 


D o it with Guidelines, a second-generation object- 
oriented graphical workbench. Guidelines lets you 
create graphical client/server applications for OS/2 

and Windows clients. A built-in __ . ____ 

prompter lets you simply point 
and click or drag and drop from 
the desktop using more than 30 
presentation manager controls. 

Guidelines utilizes JBA's high- 
level object-oriented language 
(JOT) to describe applications. 

After the application is 
designed, JOT automatically 
converts to C++ code, so you 
don’t have to learn its complex 
syntax and rules. But if you already know C++ and 
want to use it directly, you can. The conversion takes 
place regardless of the platform intended. 



Guidelines saves time and simplifies the creation of 
graphical, platform-independent applications. Its scal¬ 
able architecture lets you create anything from stand¬ 
alone PC applications to com¬ 
plex enterprise-wide business 
solutions. Guidelines supports 
DB2/2, DB2/400, DB2/6000, 
DDCS, ODBC, Q+E Lib, and SQL. 

Call for a free demo 
pack: 1-800-JBA-INTL. 

In Canada: (905) 940-2442 

JBA International 
161 Gaither Drive, Ste, 200 
Mt. Laurel, NJ 08054 
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used to report on the performance 
of new software releases. As a reg¬ 
ular process, retrieval performance 
continues to be monitored and has 
been improved with each major 
software release. Overall perfor¬ 
mance has increased by over 30% 
since the first measurement. 

We have also developed a re¬ 
gression exercise that uses an inter¬ 
nal data table feature. The internal 
data table is a spreadsheet-like fa¬ 
cility from which scripts and tapes 
can read data and then apply that 
data to the application. In our re¬ 
gression tests, we have developed 
claims data that are run through 
and automatically compared with 
baselined results* Any expected re¬ 
sult that is not matched with that 
of the baseline is documented in 
the log in a tester-customized re¬ 
port format. The results may then 
be easily examined by the test ana¬ 
lysts. This has made our regression 
testing much more efficient. 
Attrition and downsizing has de¬ 
creased testing staff by 15%, yet 
the testing being accomplished has 



Figure 2 . Empires OS/2 platform with 
application PC/System 90 at the 
"Welcome Screen." 


not diminished, and in some cases 
it has increased. 

Another method we have de¬ 
veloped is a "mapping" test. In our 
case, the OS/2 application, PC 
System 90, interfaces with a large 
IBM mainframe package system, 
as shown in Figure 2. PC System 
90 acts as a friendly front end to 
the mainframe claims system and 
converts certain data fields. It then 
uploads the data interactively to 
the mainframe. We need to know 
from version to version if this 
process is occurring without de¬ 
fects. We have written a script to 
capture and compare the input to 
the PC System 90 front end with 
the resultant input on the main¬ 
frame. Once again, a baseline ap¬ 
proach is used, and the data is au¬ 
tomatically compared by ATE Any 
errors are flagged and examined 
by the testing staff. 

To fully leverage our quality- 
improvement initiative, we see op¬ 
portunity in introducing this test¬ 
ing method in the software 
development phase to use in a unit 
test mode. This will uncover and 
prevent defects from continuing 
further into the project life cycle 
and will advance the concept of 
doing it right the first time. 
Coming from a software develop¬ 
ment background, Vve experi¬ 
enced the lack of detail knowledge 
with the data that will pass 
through the system. Using a ro¬ 
botic tool with a testbed of data de¬ 
veloped by team members that do 
have this detail knowledge will be 
a great advantage in unit testing. 

VALUE OF IMPROVED QUALITY 
AND PRODUCTIVITY 

The adoption of methods such as 
automated testing and full life 
cycle involvement has brought a 
sense of realism to our improve¬ 
ment initiative. Any organization 
that can do more with less without 
compromising quality will soon 


come to the realization that work¬ 
ing smarter not harder is what will 
benefit the bottom line and the 
front line. It is a win/win situation 
for all involved. In our case, re¬ 
gression testing, which in the past 
involved one resource for three 
days, now takes that same resource 
less than one day to perform with 
even more accuracy. The staff's 
morale and job satisfaction has in¬ 
creased. The improved process 
leads to lower costs and higher 
productivity. The resultant evi¬ 
dence is shown when quality soft¬ 
ware is put into production on a 
timely basis. This leads to cus¬ 
tomer satisfaction, and that is our 
ultimate goal. 

CONCLUSION 

As new technology is introduced 
to the business world, the organi¬ 
zations that take the risks and are 
determined to Improve the current 
methods of operation will be the 
successful ones. Process improve¬ 
ment and reengineering can lead 
to big payoffs in quality and pro¬ 
ductivity. We need to take a look at 
our traditional processes, break 
them down into their components, 
and then apply visionary thinking 
to improve them. The develop¬ 
ment and use of products such as 
OS/2 and ATF were unthinkable 
50 years ago. For all of us to fully 
participate in the improvement of 
our work, we need to look toward 
the future and continue to apply 
quality concepts. 

Joseph P. Busa CQA, is the quality 
assurance manager for Empire Blue Cross 
and Blue Shield in New York t the largest 
Blue Cross/Blue Shield in the country. He 
is responsible for ail data processing qual¬ 
ity assurance at Empire . He received his 
CQA (Certified Quality Analyst) from the 
Quality Assurance Institute in Orlando , 
Fla,, in 1990. He has a B.S. in business 
administration from New York State 
University at Oswego , New York 
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This article demonstrates using OS/2 as the development base to build products that support multiple 
platforms. By BRUCE LANDECK 


Multiple Platform 
Development 


ecause of the proliferation of PC 
operating environments, com¬ 
mercial products need to support 
multiple platforms to reach the widest 
possible audience. This article demon¬ 
strates using OS/2 as the development 
base to build a real product that runs 
under four different environments. The 
design and coding techniques and tools 
necessary to maximize code sharing be- 
tween products and minimize mainte¬ 
nance costs are explained with examples. 

OVERVIEW 

When building a PC commercial appli¬ 
cation, one of the first questions is, What 
is the target platform? In the past, the 
answer was obvious: PC/MS DOS. 
Today, while DOS is still a candidate, 
developers must also consider OS/2, 
Windows, and AIX/UNIX. DOS 
presently has the largest user base, but 
people are moving away from it. 
Windows has become very popular with 
a large user community, but it is being 
challenged by OS/2. And although 
OS/2 usage is growing rapidly, it will 
have to contend with Windows 95 
(Chicago). AIX/UNIX will never go 
away. 

One solution is to build for all of 
them or at least more than one. This ap¬ 
proach is practical only if you are able to 


write the application once and at build 
time determine the target platform. 
Otherwise, you end up writing multiple 
applications and, more importantly, 
maintaining multiple applications. 

Late last year. Spitfire Software was 
faced with this dilemma. We needed to 
upgrade a disk utility we market that 
targeted DOS and supported only a 
command line interface. It needed an in¬ 
teractive interface, additional function, 
and a broader audience. From an inter¬ 
face standpoint, both OS/2 Presentation 
Manager and Windows were attractive. 
The command line version was still a re¬ 
quirement for use in batch files and 
REXX programs. AIX/UNIX would 
have to wait because of skills. Therefore, 
the four target environments we chose 
were: 

1. OS/2 Presentation Manager 

2. OS/2 command line (non-Presen- 
tation Manager) 

3. Windows 

4. DOS command line. 

TOOL SELECTION 

Next, we selected the development envi¬ 
ronment and tools. OS/2 was the logical 
choice for the development environ¬ 
ment, since it also supports the DOS and 
Windows environments and is a solid 
operating system. C++ was chosen as 
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the development language for 
portability and productivity rea¬ 
sons. The object-oriented nature, 
tight type checking, and functional 
richness of available libraries has 
made C++ a strong application de¬ 
velopment language. 

What we did not want to do 
was code the interactive interface 
for OS/2 Presentation Manager 
and Windows at the C++ level due 
to productivity concerns. A num¬ 
ber of graphical user interface tools 
on the market allow design of the 
interface at an object level and gen¬ 
erate the code. We considered two: 
Gpf Professional Developer's 
Toolkit and JBA International's 
Guidelines. They both generate 
C++ code and interface to external 
C++ modules. We selected 
Guidelines for a number of rea¬ 
sons, none of which reflect nega¬ 
tively on Gpf. Guidelines provides 


basic facilities that significantly in¬ 
crease productivity: 
l.It is a fully integrated develop¬ 
ment environment with work¬ 
bench-supporting design, 
implementation, test, and docu¬ 
mentation activities. 

2. It supports a full set of controls, 
including CUA '91 in both OS/2 
and Windows environments 
(using IBM CUA Common User 
Access Controls Library/2 for 
Windows applications). 

3. It supports Borland C++ compil¬ 
ers for both OS/2 and 
DOS/Windows and WatCom 
C++ and IBM's C Set++ for 
OS/2. 

4. It supports multiple execution 
threads in both environments. 

5. It supports complete integration 
of external C++ modules, with 
the main module allowing as 
much application function 


placed in the external modules 
as desired. For writing the main 
module event processing func¬ 
tions, Guidelines provides a pro¬ 
prietary language, JOT, which is 
similar to Basic in appearances 
(modified to force structured 
programming) with C++ data 
typing added. It allows the addi¬ 
tion of in-line C++ statements. 
JOT is a full-function language 
in which small- to moderate-size 
complete applications can be 
written. 

We chose Borland's C++ com¬ 
piler. Although there was no other 
choice considering we needed one 
that Guidelines supported for both 
OS/2 and DOS/Windows, it was a 
good selection. 

IMPLEMENTATION 

The basic design for the project 
placed the user interface manage- 



Figure h Date stamp copy — OS/2. 
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merit functions and high-level ap¬ 
plication logic in the main module 
and all of the actual application 
function in separately compiled 
modules. One source code set was 
written for the application function 
modules, and a main module was 
generated using Guidelines for 
both OS/2 Presentation Manager 
and Windows environments. A 
second main module was written 
in C++ for the OS/2 and DOS 
command line versions. 

Developing the interactive 
user interface module with 
Guidelines was straightforward, 
and no special consideration was 
given to OS/2 vs. Windows ini¬ 
tially (Figures 1 and 2 show how 
the interface looked in both envi¬ 
ronments). We designed and tested 
the interface under OS/2. When it 
was complete, we tested it under 
Windows. At this point, we en¬ 
countered an irritant. While the 


Windows version had all of the 
components and the code ran cor¬ 
rectly, the interface did not look 
right because proportions and col¬ 
ors were different. We had to go 
back and fine-tune the interface for 
Windows. This was difficult be¬ 
cause in the design step you see 
how it looks under OS/2, not 
Windows. To see it under Win¬ 
dows, you have to build and exe¬ 
cute the Windows version. 

Implementing the C++ mod¬ 
ules was more complex. We ran 
into the following problems: 

1. The operating system header 
files (OS2.H, WINDOWS.H, and 
none for DOS) are quite different 
in specifying operating system 
data types. 

2. The OS/2 and DOS API's are 
very different. Although the 
Borland function library hides 
many of the differences, it does 
not hide them all. For example. 


OS/2 provides an API call to 
copy a file while DOS does not. 
Also, OS/2 has both High 
Performance File System (HPFS) 
and file allocation table (FAT) 
file systems, while DOS sup¬ 
ports only FAT file systems. 

3. Guidelines provides its own 
string class, which is function¬ 
ally richer than Borland's and 
has to be used in the OS/2 
Presentation Manager and 
Windows versions. It could be 
used in the OS/2 command line 
version but requires a 386 or 
higher processor. The DOS com¬ 
mand line version needed to 
support all x86 processors, so we 
had to use the Borland string 
class for that version. 

4. OS/2 has a flat address space, 
while DOS/Windows is seg¬ 
mented and requires "memory 
model" considerations. 

5. Borland's OS/2 compiler trans- 




Figure 2. Date stamp copy — Windows. 
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lates the int data type to a long 
integer type {4 bytes), while the 
DOS/Windows compiler con¬ 
verts it to a short integer type (2 
bytes). This causes a problem 
using Borland's libraries' data 
structures within JOT (which 
supports only short or long inte¬ 
ger types and does not recognize 
the int type). For example, the 
Borland date type structure: 


struct date { 

int da_year; 
char da_day; 
char dajnon; 

>; 


will result in da.year being long 
when compiled for OS/2 and short 
when compiled for DOS/ 
Windows. 

We solved each of the problems. 
Tire basic solution to the first four 
problems is to use the C++ condi¬ 
tional compile directives and macro 
facilities. To resolve which header 
files and macro definitions are used 
to establish the environment, every 
C++ module had at its beginning 
the statements in Figure 3. 

In Figure 3,_0S2__ is defined if 

you are compiling under Borland 
C++ for OS/2, and .Windows is de¬ 
fined if compiling for Windows. 
Neither is defined when compiling 
for DOS. 

In examining Figure 3, note the 
following: 

1. In the OS/2 section, "guirun.h" is 
included for access to the 
Guidelines string class. When 
working with a third-party class 
library, it is the header file that 
supplies the information neces¬ 
sary to use the methods and 
overloaded operators. The 
header file "os2.h" was included 
for two reasons: "guirun.h" 
requires it, and the module 
makes direct calls to the OS/2 
API. The three tdefine statements 
set compile time directives in 
"os2.h H and "guirun.h 11 . 


2. In the Windows section, 
"guiwun.h 1 ’ is the equivalent of 
"guirun.h”. The header file 11 win¬ 
dows, h” is included because "gui¬ 
ld un.h" requires it. 

3. In the DOS section, "strng.h" is 
required to use Borland's string 
class. The two #define statements 
define macros that in the other 
sections were defined by the 
Guidelines and operating sys¬ 
tem headers and are used in the 
code when referencing variables 
shared by the main module and 
the application function mod¬ 
ules. Since we do not have the 
other headers in the DOS sec¬ 
tion, we needed to define them 
here. 

Originally, we had planned to 
use the Guidelines string class in 
all four versions, since it had to be 
used in the OS/2 Presentation 
Manager and Windows versions 
and was functionally richer than 
Borland's string class. Therefore 
we made extensive use of that 
class's methods. For example: 

GuiStrLen(a); 

returned the length of a string. 
This method was used in allocat¬ 
ing space for a char array to 
process the string "a” in a standard 
C manner. Later, when we discov¬ 
ered we could not use the 
Guidelines string class for the DOS 
version because of processor re¬ 
quirements, we were faced with a 
dilemma. Either we used condi¬ 
tional compile directives through¬ 
out the code (selecting either 
Borland's or Guidelines' methods) 
or we had to find a "least common 
denominator" that would work for 
both. The solution was easy. In the 
case of retrieving the string length 
for all versions, we changed the 
statement to: 

strlen{(const char *) a); 

Both the Borland and Guidelines 


string class provided for casting a 
string as a constant char array. 

To set various limits that de¬ 
pend on a flat vs. segmented ad¬ 
dress space or the file system being 
used, the macros in Figure 4 were 
defined. Borland does include a set 
of predefined macros for limits in 
"U_mits.tr that could have been 
used for the path and file name 
size values. The list was incom¬ 
plete from our standpoint, so we 
decided to create a list tailored to 
our needs. 

Conditional compile directives 
were used in the code itself for 
special cases, as illustrated in 
Figure 5. The Borland library han¬ 
dles many of the differences in 
code for the environments, but 
when directly calling operating 
system API's, you must handle 
the differences. For example, the 
application module that copies a 
file uses the API function under 
OS/2 but needs to do the physical 
copying itself under DOS and 
Windows, 

In Figure 5, the first part de¬ 
fines the common variables used in 
both environments and is followed 
by the variables used in only one 
environment. The code section 
starts with the code common to 
both, continues with code specific 
to one or the other environment, 
and ends with the common exit 
code. Also note that the macros in 
Figure 4 define the size of the 
buffers used in Figure 5. 

After examining Figure 5, it 
can be argued that what we have 
is in fact two separate programs 
built as one but as hard to main¬ 
tain as two. I would agree if this 
was the rule, but it is the only 
place in the application where the 
code itself needed to be different 
depending on the environment. In 
all other places, Borland's com¬ 
piler handled the differences 
through its libraries. 

How the C++ int type is han¬ 
dled is a different problem because 
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it effects the JOT code, which does 
not support compile directives and 
macros. What JOT does is allow us 
to write in-line C++ code that is 
passed directly through to the 
compiler. For example, if we have 
a variable that is shared with the 
application C++ modules and de¬ 
fined as an int, we can process it as 
shown in Figure 6 (JOT uses a 
semicolon to denote the start of a 


comment). The one drawback of 
this approach is that the variable 
can be referenced by only in-line 
C++ code. 

Although the code fragment in 
Figure 6 is nonsense, it illustrates 
adding C++ code to JOT modules. 
Guidelines does let us create func¬ 
tions that are entirely C++. The 
problem is that it does not syntax 
check in-line C++ code at genera¬ 


tion time. It is not until you com¬ 
pile the code that you discover er¬ 
rors. With JOT statements. 
Guidelines provides very rigorous 
checking, and if the code generates 
C++, you know it will compile. 

The last problem concerns 
memory models and processors. 
The solution here is quite straight¬ 
forward and handled by the make¬ 
files. One large makefile could not 



•ifdef_0S2„ 

•define INCL.BASE 
•define DICLJOPH 
•define INCL.DQSFILEHGR 
•include <os2.h> 

•include "d:\guide\sy s\guinin.h M 

•ifdef .Windows 

•include <windows.h> 

•include f, d: \guide\sys\guiwun. h fl 

•else 

•include <strng,h> 

•define SHORT short 
•define LONG long 
tendif 
•endif 

Figure 3 . Externa! C++ module environment statements. 



Figure 4 Externa! C++ module system parameters. 


// test for OS/2 
// OS/2 base/functions 
// OS/2 no PH 
// OS/2 File manager 
// required for guirun.h 
// Guidelines OS/2 header 
// used for String class #else 
// Windows or DOS 
// test for Windows 
// Windows functions 
// Guidelines Win header 
// used for String class 
// DOS 

// use BCC string class 
// define macros defined 
// in windows.h or os2,h 
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If! 


/* Routine to copy file fn on path fp to path tp. Input: 
Source directory 
Target directory 
Return: 0 no error 

-1 target path does not exist 
+1 other disk error 

*/ 

int fcopyCchar * fn, char * fp, char * tp) 

{ 

/* common variables */ 
unsigned char * tpn; 
unsigned char * fpn; 
int frc = 0; 

/* environment specific variables */ 

#ifdef _QS2_ 

ULOKG OpHode; 

IPIRET re; 

#else 

char * buf; 
int inh; 
int outh; 
long total; 
unsigned len; 
unsigned fdate; 
unsigned ftime; 
unsigned attrib; 

Sendif 


File name 


// to file name and path 
// from file path and name 
// function return code 


// test for OS/2 
// OS/2 copy mode parameter 
// OS/2 function return code 
// DOS/yindows environment 
// read/write buffer 
// read handle 
// write handle 
// file size 

// length of read/write record 
// file date 
// file time 
// file attribute 


/* common code */ 

/* allocate buffer for source path/filename */ 
if (NULL = (tpn - (char *) maHoc(MIPHTH + 1))) 

{ 

//process error 

> 


. more common code 

/* environment specific code */ 

tifdef _0S2_ 

OpHode ^ DCPY_EXI5TCNG; 
rc = DosCopy(fpn,tpn,QpMode); 
if (rc != 0} 

{ 


// test for OS/2 
// setup call to file copy 
// execute call 
// test for error return 


else frc = 0; 

#else 

/* allocate disk read/urite buffer */ 
if (NULL (buf = (char *) malloc{HMBUF))) 
{ 


// process error 

// do physical copy in DOS/Windous environment 


Figure 5 Example external C++ function {continued on page 37). 
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Figure 5. Example external C++ function (continued from page 36). 



be used since the OS/2 build 
needed to take place under OS/2 
while the DOS/Windows build re¬ 
quired DOS. The Guidelines mod¬ 
ule required only instructions 
telling it which environment to 
build. For the external C++ code, 
three projects were set up under 
the Borland IDE: OS/2 (one project 
handled both Presentation Man¬ 
ager and command line), Win¬ 
dows, and DOS. They all use the 
same source code but have differ¬ 
ent compile time options and place 
their intermediate and final output 
in different subdirectories. The one 
small irritant is that a complete 
build requires the execution of the 
makefiles for the three Borland 
projects followed by the two builds 
of the Guidelines graphical user in¬ 
terface. It would be nice if 
Guidelines allowed the inclusion 
of the Borland makefiles in the one 
it generates. 

DOCUMENTATION: 

The on-line documentation and 
context-sensitive help was easy to 
implement under Guidelines, 


which has a complete help text 
generation facility built into it. 
During development of the OS/2 
Guidelines module, we added the 
help text as we went, creating 
hyper text links and organizing it 
in document form. This way we 
had both an online document the 
user could read and print plus con¬ 
text-sensitive help panels. 

At generation time. Guidelines 
generated the complete .IFF file 
for OS/2. For the Windows ver¬ 
sion, Guidelines generated the 
.RTF file converting our IPF tags 
to RTF tags. We encountered one 
problem here. Guidelines was 
able to translate many IPF tags 
but not all. We therefore had to 
edit the Windows help text, re¬ 
placing selected IPF tags with RTF 
tags. During the compile/link 
phase, the IPF/RTF files were au¬ 
tomatically compiled into the 
.HLP file and linked to the exe¬ 
cutable. A great side effect was 
that we were able to take the .IPF 
file generated by Guidelines and 
easily create the printed docu¬ 
ment shipped with the product. 


SUMMARY 

As shown, the tools now exist to 
easily develop products for multi¬ 
ple platforms. Key to doing this is 
a thorough understanding of each 
platform and proper planning and 
design during the initial stage of 
the project. A strong multiple plat¬ 
form compiler is required, and a 
multiple platform graphical user 
interface design tool significantly 
increases productivity. 

Bruce W. Landeck is president of 
Spitfire Software (325 Breakwater Ridge; 
Atlanta, Ga. 30328; (404) 257-0187), which 
develops financial and utility software for 
multiple PC platforms. Bruce founded 
Spitfire Software in July 1993 after 30 
years of experience with IBM in software 
development. While at IBM, he held a full 
range of technical and managerial posh 
tions, including lead programmer, archi¬ 
tect, product planner, development man¬ 
ager, product manager, and business area 
manager. He has a B.S. degree in 
Engineering Science from Purdue 
University and an M.S. degree in 
Aerospace Engineering from the University 
of Arizona. 
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JOT function: 

function window*okay.dickO 

; b is defined externally as a long 
; JOT integer gobal variable 
t: int c = 2; // C++ inline code 



c: b += c; // C++ inline code 

return ; JOT return 

end 



Figure ft Using C++ in JOT 


If you're developing client/server 
systems, there's one more question 
you should be asking: How am I 
going to test them? 


Networking? 
Platform? 




You can’t rely on old-fashioned 
manual testing methods to test 
complex, client/server applications* You need 
to automate your testing with a tool designed 
for client/server, ATF is the tool-of-choice for 
over 100 corporations building client/server 
applications under OS/2, Windows, and NT* 

To iearn more about ATF, call 617-576-2257. 

(Or FAX 617-864-7747*) 

The Softbridge 

Tn i y Automated Test Facility 

Softbridge, Inc, *125 CambridgePark Drive * Cambridge MA 02140 


bflRCODf ffflTWtlfM. 

..OS/2 

Are you seeking ways to increase your productivity and 
data accuracy while lowering your overall cost of data col¬ 
lection? Look no further than bftRCODf flftYWHfPf for 
Automatic Document Indexing Solutions. 


Features: 

Any Angle 
Any Background 
Over 60 Pages per Minute 
Internal Consistency Checks 
Developers Kir also Available 
Pop-up Editor for Invalid Barcodes 
Optional Zoning for Faster Throughput 

The only barcode we can not read is one which is pasted on the 
back side of a page 


Solution Technology, Inc. 

i 101 S. Rogers Circle* Building 14* Boca Raton, FL 35487 
phone: {407) 241-3210 fax: (407) 997 6518 

bKOOT ttTwttrc is a trademark of Solution Technology 
OS/2 is a trademark of IBM corporal ion 
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Object-Oriented Programming Using SOM 
and DSQM 

by Christina Lau 

This comprehensive guide takes up 
where the SOM user documentation 
leaves off, providing easy-to-understand 
examples and clear instructions that will 
have first-time users as well as SOM 
veterans creating SOM- and DSOM- 
based applications that work. 

Includes disk, 

0-442-01948-3 $39.95 


Running Windows Applications 
in OS/2 

by Ayodele Anise. Teresa Be hr Beck, 
and Jean N, Shortley 

How do you make Windows 3.1—and 
the thousands of applications that run 
under it—even more powerful? By 
optimizing Windows to run under the 
OS/2 environment and taking advan¬ 
tage of the advanced features that 
only OS/2 can provide, 

0-442-01924-6 $34.95 


OS/2 and NetWare" Programming 

by Lori Gauthier, Morgan Adair, and 
Wayne Taylor 

The only book to link Netware to OS/2, 
this excellent reference guide and tutori¬ 
al offers in-depth chapters on NetWare 
Client support for OS/2 and NetWare 
Client SDK, Includes disk. 
0-442-01815-0 $36.95 

Developing OS/2 Multimedia 
Applications 


Lotus Notes Release 3 in the OS/2 
Environment 

by Tony Walsh 

What happens when nearly one million 
users implement the new release of Lotus 
Notes, the premier client/server 
Groupware application? System adminis¬ 
trators and advanced users in OS/2 will be 
searching for ways to make the most of its 
powerful new features. Includes disk. 
0-442-01890-8 $36,95 

Objects for OS/2' 

by Scott Danforth, Paul Koenen, and 
Bruce Tate 

Integrates the System Object Model 
with OS/2 dent server functions, 
Explains how OOP and SOM function, 
why they are important, and how they 
relate to OS/2. Indudes disk. 

0-442-01738-3 $36 95 


Dynamic Data Exchange for OS/2" 
Programmers 

by Glenn Puchtel 

Well-organized and straightforward in its 
presentation of sometimes complex top¬ 
ics, this book is a valuable addition to 
the reference collection of all program¬ 
mers, particularly those whose resposi- 
bilities include connecting Windows and 
OS/2 appications includes disk. 
0-442-01949-1 $36.95 

OS/2" C++ Class Library 

by Kevin Leong, William Law, Robert 
Love, Hiroshi Tsujl and Bruce Olson 

This sweeping guide to the User 
Interface Library is packed with design 
rationale, tips for designing classes in 
C++, and tips for programming to the 
Presentation Manager. Incudes disk. 
0-442-01795-2 $36.95 


by William W. Lawton, Bradley Noe, 
and Marcelo Ft, Lopez, Jr. 

This programming guide provides read¬ 
ers with an understanding of the overall 
architecture of MMPM/2, and its sub¬ 
systems, and shows how to best use 
the functionality provided by these sub¬ 
systems. Includes disk. 

0-442-01929-7 $39.95t 

OS/2 Presentation Manager" DPI, 2nd Ed. 

by Graham G.E. Winn 
Application program developers will find 
comprehensive, up-to-date information 
on the new GPI features of the OS/2 
Presentation Manager as well as count¬ 
less programming tips, hints and pitfalls 
to avoid. Includes disk, 

0-442-01939-4 $39,95 

Order directly from the Publisher by 
calling 1 800 842-3636 (Dept. Z1660) or 
stop by your local bookstore. 


Client/Server Survival Guide with OS/2* 

by Robert Orfali and Dan Harkey 

0-442-01798-7 $39.95 


The RS/2* 2.1 Corporate Programmers Handbook 

by Nora SchoEin, Martin Sullivan, and 
Robin Scragg 0-442-01598-4 $39,95 


Client/Server Programming with OS/2* 3rd Ed. The GUI-OOlil War: Windows vs. OS/2* 

by Robert Orfali and Dan Harkey 

0-442-01833-9 $39.95 


Developing C/C++ Software in the OS/2" 
Environment 


by Theo Mandel 

0-442-01750-2 $29.95 

OS/2" Quick Reference Library 
Volume 2: Message Functions 


by Mitra Go pa u I 0-442-01240-3 $39.95 by Nora Scholin 0-442-01 898-3 $19.95 


OS/2 Rexx Handbook: 

Basics, Applications, and Tips 

by Ha E let Ge r m an 0-442-01734-0 $34.9 5 

OS/2 Application Programmer’s Guide 

by Jody Kelly, Craig Swearingen, Dawn 
Bezviner and Theodore Shrader 

0-442-01736-7 $34.95 

Van Nostrand Reinhold 


1 15 Fifth Avenue, New York, NY JQ003 
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Memory leaks adversely affect your programs' performance and can even cause your machine to 
stop processing. Here are five ways to avoid and plug memory leaks. By STEVE HARGIS and 


MIKE SKELTON 


Plug Those 
Memory Leaks! 


11 computer programs use mem¬ 
ory, some for the program code, 
some for the data. Some pro¬ 
grams call libraries that then use more 
memory. Data can be held in numerous 
ways, such as structures, heaps, and 
stacks. The operating system itself will 
use memory on behalf of a program. For 
example, even the mouse pointer shape 
is held in memory for the program 
using it. Since program memory can be 
held by many owners in many ways, de¬ 
termining all the memory that is directly 
used by a program or indirectly used on 
its behalf is an involved task. In this arti¬ 
cle, we define different kinds of memory 
usage problems, offer some design 
guidelines to follow during program de¬ 
velopment, and show an approach to 
debugging memory leaks. 

Since a program uses memory in 
many ways, in many places, and with 
many owners, it would not be surpris¬ 
ing if some programs lost track of a little 
bit of memory every now and then. So 
what? Well, the consequences depend 
on how much and how fast the program 
loses track of its memory. 

Following are three examples of 
programs and the consequences of their 
memory use: 

1. A small utility program runs for a few 
seconds, doesn't keep track of any of 


its memory, and relies on the operat¬ 
ing system to free its memory when it 
ends (and hopes no one notices). 

2. A business application that runs a few 
hours needs to seriously track its 
memory usage to prevent the user 
from perceiving any affect of lost 
memory. However, if the lost memory 
is large enough, the user will notice 
the application (and the system in 
which it runs) is becoming slower or 
encountering errors for mysterious 
reasons. The user may need to end the 
program and restart it to make the 
business application run well again. 

3. A mission-critical application that is 
expected to run 24 hours a day, seven 
days a week cannot afford to lose 
track of any memory at all because 
the entire system will become slow, 
unresponsive, and incapable of per¬ 
forming at required levels. 

All three examples need to manage 
their memory flawlessly. Plugging mem¬ 
ory leaks is an integral part of improv¬ 
ing reliability and performance. 

MEMORY LEAKS 

A memory leak is memory a program 
allocates (or that is allocated on a pro¬ 
gram's behalf) that is not freed after the 
program is finished with it. If the same 
action is executed again, the program 
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Fast Visual Application Development 

for OS/2 and DB2 


If you’re looking for fast and easy application 
development for OS/2, then take a look at the award¬ 
winning Watcom VX*Rexx visual development 
environment, VX*REXX lets you build applications to 
exploit the graphical user interface, multi-threading, 
and multi processing power of OS/2, VX*Rhxx 
C lient/Server Edition gives you the added power to 
access DB2 or other database systems, manipulate the 
data, and chart the results at lightning speed. 

“We like VX*REXX> Using it for development feels like 
driving a Porsche: it's fast, it’s compact, everything 
in the right place , and it makes us look good, too. ” 

Peter Coffee, PC WEEK 

Designed to Meet Your Needs. 

Watcom VX'REXX combines a project management 
facility, visual designer and an interactive debugger to 
deliver a highly productive visual development 
environment. The Client/Server Edition includes 
additional powerful objects so you can rapidly create rich GUI database 
applications. You can create OS/2 client applications which connect to 
DB2/2 or DB2/6000. Use IBM’s DRDA support on OS/2 to access DB2 for 
MVS, DB2/400 for AS/400, and DB2/VSE and VM (SQL/DS) for VM and 
VSE, Also supported are Watcom SQL and ODBC-enabled databases. 

H Overall , this edition ofVX*REXX for OS/2 is an outstanding visual 
client/server development platform. ” Nicholas Petreley, Info World 


Point. Click. And Presto! 

To create an application you draw user interface objects, customize their 
properties using standard OS/2 notebooks, and define their event code using 
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allocates more memory instead of 
using memory previously allocated. 
With repeated executions, the pro¬ 
gram accumulates more and more 
memory. Negative affects of mem¬ 
ory leaks include the accumulation 
of memory by the leaking program 
causing other processes' code or 
data to be swapped or paged out. 
Soon, the system's resources are 
consumed while the operating sys¬ 
tem swaps memory in and out in¬ 
stead of executing application code. 
This robs every process in the sys¬ 
tem of performance. 


MEMORY OVERWRITE/ 

MEMORY WALKER 

A memory overwrite occurs when 
a program allocates less memory 
than it actually writes. The effect is 
to overwrite and possibly wipe out 
data that happens to be located im¬ 
mediately after it in memory. 
Whether or not a memory over¬ 
write occurs depends on how 
many additional bytes are stored 
beyond the amount allocated. The 
observable symptom is intermit¬ 
tent data corruption, which is de¬ 
pendent upon the length of data 
stored in memory (not an intuitive 
item to check). 


MEMORY NEUTRALITY 

This is the desired memory use 
quality of programs* A module, 
component, function, API, pro¬ 
gram, system, and so on is said to 
be memory neutral if it: 

* Deallocates all memory for 
which it is responsible 

* Does not attempt to deallocate 
more memory than that for 
which it is responsible. 

The basic definition is straight¬ 
forward: deallocate all and only 
the memory that you allocate. 
However, when specification stan¬ 
dards call for a different module to 
deallocate memory than the mod¬ 
ule that allocated the memory, the 
definition gets a little fuzzy. This is 
not a recommended specification* 


Now that we know what 
memory leaks are and how they 
affect the performance of an appli¬ 
cation as well as each process exe¬ 
cuting on a system, five recom¬ 
mendations follow that allow 
developers to detect and fix leaks 
early in the product development 
process. 

DESIGN AND PROGRAMMING 
RECOMMENDATIONS 

2. Know the memory usage of each 
component within the product. 

it is difficult to diagnose mem¬ 
ory problems when no one knows 
how the product is supposed to 
use memory. The logical person to 
know the memory usage is the de¬ 
veloper, who possesses some basic 
memory debugging skills and 
tools* 

To check your knowledge of 
the memory usage of your applica¬ 
tion, select a test case that is typical 
for a user Assume that you are 
going to execute the test case while 
your application is executing. How 
much memory do you think will 
be allocated during the test case? 
How much memory will be com¬ 
mitted? Do not forget to specify 
whether the memory will come 
from the heap or be part of shared 
memory, and so on. 

Check your answers with a 
memory analyzer, such as The- 
seus2 (part of the SPM/2 
product), 1 With Theseus2, from the 
initial window, select the process 
executing your application, then 
choose the Memory Utilization op¬ 
tion from the Process item on the 
menu. When compared with re¬ 
sults before the test and results 
during the test case, the Total 
System, Total Shared originated, 
and Total Private rows will allow 
you to check your answers* (It may 
be desirable to explore memory 
further with Theseus2 to see ex¬ 
actly what memory was allocated 
by whom, what the contents are of 
some memory, or why the size al¬ 


located is not the same as what 
your application asked for.) 

2* Do not rely on the operating 
system to delete memory when the 
process dies * 

This is common practice with, 
it would seem, no ill effects. It is 
true that the operating system will 
deallocate resources when the 
process dies, but that works only 
for relatively short-lived processes. 
Major processes that stay up for 
days, weeks, or months should not 
be implemented that way. There 
are five main reasons 24/7 
processes and, arguably, even 
shorter-lived processes should not 
rely on the operating system to 
delete resources. 

First, resource consumption 
will grow over tune, and the oper¬ 
ating system may not clean up 
memory structures in a timely man¬ 
ner. For example, if memory is allo¬ 
cated to store information until a 
process dies and the process does 
not die for three weeks, the infor¬ 
mation stored will consume a lot of 
memory. Consuming a lot of mem¬ 
ory will cause memory (wherever it 
is used the least) to be swapped. It 
will not take long for the swapper 
file to be so large that it adversely 
affects the performance of every¬ 
thing that runs on the machine. 

The second reason is that the 
code may be ported or expected to 
run on a different operating sys¬ 
tem or platform with different 
clean-up characteristics. The new 
platform may not clean up re¬ 
sources as nicely as OS/2. Or per¬ 
haps the other platform does clean 
up nicely today, but it may not Ln 
the next release. 

Reason three relates to device 
drivers. Device drivers can, and 
many do, allocate locked and resi¬ 
dent memory on behalf of an ap¬ 
plication, Unless this memory is 
deallocated by the device driver, it 
will always be allocated* 

A fourth reason to not rely on 
the operating system to delete 
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memory when a process dies is that 
program design changes may alter 
the operating system's ability to 
clean up memory structures. Code 
may originally be written to run in 
a process of its own, but the process 
or thread model of products is sub¬ 
ject to change. Code may be consol¬ 
idated from several processes into a 
smaller number of longer-lived 
processes to avoid process creation 
and deletion overhead. Therefore, 
code that started out in a process of 
its own may be consolidated to run 
on threads of a process containing 
other threads. Resources such as 
memory, semaphores, and files are 
owned by the process, not by the 
thread. So when the code now ter¬ 
minates the thread, the process re¬ 
mains—along with all the resources 
accumulated by the thread but 
never freed. 

The last reason is that debug¬ 
ging is greatly complicated by not 
knowing whether memory is sup¬ 
posed to be unallocated by the op¬ 
erating system or if a memory leak 
exists. We advocate use of the C 
Set/2 and C/C++ debug memory 
functions. 2 When using them, we 
have noticed that many programs 
are not memory neutral at the in¬ 
struction immediately prior to re¬ 
turning control to the operating 
system. So if we are trying to fix a 
memory leak, we must first get 
through the "noise" of memory 
that is supposed to be cleaned up 
by the operating system (we say 
that memory was leaked purpose¬ 
fully) to memory that is being 
leaked accidentally. This is an ex¬ 
tremely time-consuming activity, 
especially if the developer does not 
know the memory usage of his or 
her component. 

Let us close this recommenda¬ 
tion by saying that sound coding 
practices include allocating ma¬ 
chine resources as needed, tracking 
those resources, and deallocating 
them at the earliest reasonable 
time. Relying on the operating sys¬ 


tem to dean up a process's use of 
resources is dangerous in today's 
cross-platform code environment. 

3 . Avoid designs where one mod¬ 
ule allocates memory and another 
module deallocates it 

The exception, of course, is 
when the design specification 
comes from a standards institute 


and you have no control over it. 
This sort of design can lead to the 
following problems: 

* Poor communication between 
memory allocation and dealloca¬ 
tion modules, or developers, will 
lead to memory leaks. 

• There is an increased possibility of 
several modules using different 
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linking conventions (for example, 
optlink and syslink). This causes 
applications to leak memory since 
memory allocated under one link¬ 
ing convention may not be recog¬ 
nized under another. 

Few people, if any, will really 
know who is allocating what for 
what or who can deallocate or 


reuse what under what conditions. 
Communicating that to team 
members will be extremely diffi¬ 
cult, as will answering and de¬ 
bugging memory usage questions. 

4. Minimize the number of differ¬ 
ent compilers used in the product. 

Using multiple C run-time li¬ 
braries to compile different mod¬ 


ules will lead to memory leaks be¬ 
cause run-time libraries do not im¬ 
plicitly communicate with one an¬ 
other A corollary to this suggestion 
is that different versions of the 
same compiler often have the same 
problem because the header files 
used to make the libraries are not 
the same between versions. It is ex¬ 
tremely difficult, if not impossible, 
to cleanly separate functions within 
modules or modules within appli¬ 
cations among different C run-time 
libraries. They inevitably will want 
to communicate, but compilers do 
not support communications across 
run-time libraries. 

5. Set the criteria for determining 
memory neutrality early in the devel¬ 
opment cycle. 

We recommend that memory 
neutrality be a test exit criteria be¬ 
ginning with the functional verifi¬ 
cation test. If an application has 
memory problems, finding and fix¬ 
ing them as soon as possible in as 
small an environment as possible is 
much easier than waiting for tests 
in a large, complex environment. 

DEBUGGING TECHNIQUES 
AND TOOLS 

OS/2 memory usage includes 
these three facts: when a program 
allocates memory, it acquires a 
memory object; memory is owned 
by the process that allocated it; and 
a program may have multiple 
threads of execution in a process. 
So a memory object allocated by 
any thread is owned by the process 
and may be shared between all of 
the threads in the process. 

When debugging, the first 
question to ask is, Which of the 
many processes running in the sys¬ 
tem have memory leaks? Once the 
leaking processes have been deter¬ 
mined, the next question is. Which 
memory objects in the processes 
have memory leaks? The last ques¬ 
tion to ask is. What piece of code is 
allocating the memory objects and 
what should be deallocating them? 
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In the remainder of the article, 
we describe how to discover if 
your application is leaking mem¬ 
ory* If you do have a memory leak, 
our detection technique will 
quickly indicate which part of 
your application is responsibte. 
Useful tools to complement our 
technique are also discussed* The 
first necessary tool is a memory 
analyzer, which opens access to the 
entire contents of memory. The 
second is part of the IBM C Set/2 
or IBM C/C++ compiler/ Other 
compilers or third-party add-on 
products offer similar capabilities. 
Detailed discussions and examples 
using these tools are available, 4 

Depending on the type of leak, 
you can use either a memory ana¬ 
lyzer or compiler tools to diagnose 
the cause of the memory leak. Since 
leak detection begins with a mem¬ 
ory analyzer, we will cover them 
before we cover compiler or com¬ 
piler add-on tools that are helpful, 

MEMORY ANALYZERS 

Maneuvering through the laby¬ 
rinth of OS/2 memory structures is 
a chore that few developers try to 
complete. Fortunately, tools exist 
that will navigate through OS/2 
memory and report what is occur¬ 
ring. Memory analysis is made 
possible by tools that access sys¬ 
tem and kernel memory; report on 
process and memory object owner¬ 
ship; understand linear and physi¬ 
cal memory addressing; can access 
shared, swapped, and present 
memory; and detect memory leaks, 
among many other capabilities. 
Theseus2 is the most complete 
OS/2 memory analysis tool avail¬ 
able; its documentation and online 
help contain years of memory de¬ 
bugging experience and advice (in¬ 
cluding an "Explanation of the 
contents of this window" menu 
choice for every window)* A tutor¬ 
ial for the memory leak detection 
functions of The$eus2 is available. 5 

To confirm that a memory leak 


exists, use the system level mem¬ 
ory leak detection function in 
Theseus2. When a memory leak 
exists, Theseus2 will report that a 
process (or processes) is not deallo¬ 
cating all of the memory that was 
allocated. (Focus your attention on 
the processes that you can start 
after the leak detection function 


has started and the processes that 
complete before the leak detection 
function has completed. Thus you 
would usually ignore system and 
Presentation Manager processes.) 

By confirming the existence of 
a memory leak, we have also dis¬ 
covered which process is leaking 
(this is called system level leak de- 
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tection). With this knowledge, we 
would apply the memory analyzer 
to only the process that is leaking to 
discover which memory objects are 
leaking (this is called process level 
leak detection), in Theseus2, this 
would require use of the "Memory 
Object Leak Detection" function, 
which monitors a specific object in 
memory and reports the status of 
each page within the object (this is 
part of object level leak detection). 
As time progresses, changes in the 
status of a page are reported along 
with a detailed description of what 
changed at what memory address. 
This information is extremely help¬ 
ful because we can learn: 

• The size of the memory object 

• The contents of the memory 
object 

• The status of each page within 
the memory object. 


Theseus2 allows leak detection 
in a manner that continually nar¬ 
rows the search. The results from 
system level leak detection indi¬ 
cate a process or processes; the 
process level indicates a memory 
object or several objects; and object 
level leak detection indicates a 
page or set of pages. Each level of 
leak detection points to a lower 
level of memory abstraction until 
memory pages are reached. 

Armed with this information, 
we can find the developer respon¬ 
sible for using that memory object 
and determine if the behavior we 
are seeing is expected. It can be 
helpful to ask questions such as. 
Do you recognize the data in this 
memory structure? What size 
should this memory structure be? 
Is the size of this memory structure 
static or dynamic? When was this 


memory structure allocated and 
when is the earliest possible time 
that it can be deallocated? If the de¬ 
veloper can answer these questions, 
then either the design included a 
memory leak (that is, the developer 
never planned to deallocate the 
memory) or comparing the answers 
to the code will uncover a discrep¬ 
ancy between the design and the 
implementation. Either way, the 
memory leak will be obvious. 

If the developer cannot answer 
the questions, you may have to 
continue your debugging using the 
compiler tools discussed ahead. 
You may also want to refer that de¬ 
veloper to the first design and pro¬ 
gramming recommendation at the 
beginning of this article. 

A useful memory analyzer will 
allow you to analyze memory from 
several perspectives. Depending 
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on how much you know about the 
memory leak at hand, analyzing at 
the system, process, thread, exe¬ 
cutable, or memory object level can 
be helpful. Being able to monitor 
swapper file growth and page 
swapping is also helpful in deter¬ 
mining if a memory leak exists. We 
have used TheseusZ to detect and 
solve many memory leaks by first 
determining which process is leak¬ 
ing and then examining that pro¬ 
cess in finer granularity until the 
actual memory object being leaked 
is found. Once you know the mod¬ 
ule or memory object that is leak¬ 
ing, you can apply the compiler 
debug memory tools if necessary. 

COMPILER TOOLS 

The IBM C/C++ Tools compiler 
contains a battery of debug mem¬ 
ory management features. These 
features consist of debug versions 


of the calloc, free, _heapmin, maHoc 
and realloc functions. The debug 
versions are, respectively, .debug, 
calloc, _debug_free, _debug_heapmin, 
_debug_malloc, and _debug_realloc. 
There is also a _dureallocated func¬ 
tion that outputs information 
about every memory object on the 
heap. (Version 2 of the compiler 
also supports debugging the new 
and delete operators.) 

The compiler can be told to 
use the debug versions of the 
memory management functions in¬ 
stead of the regular versions at 
compile time with a compiler 
switch. When you turn the switch 
on, each memory function call au¬ 
tomatically invokes its debug 
equivalent and another debug 
memory function called _heap_check, 
^heap^check performs a thorough 
check of the heap, its memory ob¬ 
jects, and all associated pointers. If 


anything is out of order, processing 
is aborted and a diagnostic mes¬ 
sage is output on stderr. At first it 
may be annoying that processing is 
aborted, but it is helpful to know 
that memory was overwritten or 
that a bad pointer was passed to a 
memory function. 

When a program aborts due to 
memory errors, it is common for 
the run time to indicate that the 
error was before or after module x 
line y. An error message like this 
indicates that an error was just de¬ 
tected; therefore, the actual error 
occurred between the line refer¬ 
enced in the message and the last 
memory function called {specifi¬ 
cally, the last _heap_check per¬ 
formed). Finding the memory 
function that executed just prior to 
the one flagged is usually easy, but 
it can be quite difficult in a multi¬ 
threaded environment. The hunt is 
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worthwhile, however, since there 
are many benefits to letting the 
compiler find memory errors. 

The compiler is the definitive 
source as to whether or not a mod” 
ule has memory leaks. A home¬ 
grown memory check scheme may 
suffer from the same blind spots as 
the code it was intended to check. 
We know of no better way to en¬ 
sure that the memory management 
functions are used in a memory 
neutral way than to use a compil¬ 
er's debug memory management 
features. Some memory errors are 
detected only when the memory 
debug functions are turned on (for 
example, passing a bad pointer to 
free and some memory overwrites). 

Generally, compiler tools are 
not hard to use; although some 
code additions may be required for 
C++ code that redefine or overload 
the new and delete operators. We 
recommend locating the point in 
your code where you return con¬ 
trol to the operating system (your 
code should be memory neutral 
here). Just prior to this point, add a 
call to the jJump^allocated function 
that is conditional based on a flag 
the compiler turns on when the 
debug memory management calls 
are used. For example: 

iifdef „DEBUGJL1QC_ 

_dump_a!Located(i6); 

#endif 

It can also be useful to use 
_dump_aIlocated before and after a 
function, operation, or test case is 
executed to determine if the func¬ 
tion, operation, or test case is actu¬ 
ally memory neutral. 

After compiling with the 
debug memory options turned on, 
your application may behave dif¬ 
ferently. it will definitely execute 
more slowly—approximately dou¬ 
ble previous execution times. 
When the heap is in a good state, 
you should be able to run a test 
case and then shut down your ap¬ 


plication. Just before control is re¬ 
turned to the operating system, the 
_dump_alIocated call will print infor¬ 
mation about heap storage that is 
still allocated. Ideally, it will say 
that your application has no stor¬ 
age allocated. If you do have stor¬ 
age allocated, then you have a 
memory leak! The report is sent to 
stderr and includes the line num¬ 
ber and name of the module that 
allocated the memory, the pointer 
that points to the memory, how 
much memory was allocated, and 
the first 16 bytes of that memory 
location (the parameter 16 can be 
changed to as much or as little as is 
helpful to you). 

SUMMARY 

Customers are demanding applica¬ 
tions that can maintain peak per¬ 
formance for weeks or months 
without needing to be restarted. 
Even small memory leaks will 
cause an application to grind the 
entire system to a halt; so detecting 
and plugging memory leaks is an 
important part of performance. 

Compiler debug memory fea¬ 
tures and memory analyzers are 
indispensable tools in avoiding 
and plugging memory leaks. 
Memory analyzers allow memory 
leaks to be quickly detected; they 


can also be used to narrow the 
hunt to specific modules or mem¬ 
ory objects. Compiler debug mem¬ 
ory tools can then be used to moni¬ 
tor the behavior of specific 
modules and to flag incorrect 
memory usage. 

Nothing beats having the right 
tools for the job! 

Steve Hargis joined IBM Austin in 1991 
to work on the Parallel Database Manager 
project. He subsequently joined the LAN 
Systems Performance Group. Steve has an 
M.Sin database theory from Arizona 
State University and a Ph.D. in information 
systems from The University of Texas in 
Austin . He has authored one book about 
qualitative , computer-supported negotia¬ 
tions and written several articles on per¬ 
formance topics , Steve can be reached via 
Internet at hargis@vnet.ibm.com or by 
phone at (5121838-0560. 

Mike Skelton joined IBM in 1977 after 
receiving a B.SII ■ and MS.E from the 
University of Texas at Austin. Mike has 
designed LSI chips , written device drivers 
and operating system extensions, and ana¬ 
lyzed system performance , Presently, he is 
a system performance analyst for OS/2 
LAN System products. He has published 
numerous papers about computer algo¬ 
rithms , performance , and performance 
tools . 


REFERENCES 

1. IBM System Performance Monitor/2 2.0. (Software available from 1-800- 
IBM-CALL) 

2. IBM C/C++ Tools 2,00 C Library Reference, 2nd edition, March 1993, pp. 42- 
44 and under the specific function names. (IBM order number: S610-1183-00.) 

3. IBM C/C++ Compiler 2.01. (Software available from 1-8004BM-CALL.) 

4. Steve Hargis, Mike Skelton. Memory Debugging for C and C++ Programs, 
IBM White Paper, LAN Systems Performance, March 1994, (Available in 
PostScript on CompuServe in section OS2DF2 in library 9 as memlks.exe 
(self-extracting file into memleaks.ps).) 

5. Steve Hargis, Mike Skelton. Memory Leaks, IBM White Paper, The 
Developer Connection for LAN Systems, VoL 1, September 1994, (Available 
from 1-800-6DE VCON,} 


48 


0 S / Z DEVELOPER 



Attend the only show that has all the tools you 
need to make your development vision a reality. 



Your mind is your livelihood. And in a world of converging 
technologies, you need to fill it with more than just the 
buzzwords. New technologies are supposed to 
solve your development problems. Yet for every 
problem solved, you know a new one will emerge. 

Software Development 95 takes you beyond 
the buzzwords — from component to full-scale 
enterprise application development, we show 
you how to create tangible, real-world solutions. 

We explore the issues surrounding object-oriented 


SOFTWARE 



«5nFIBENCE it 


programming, client/server migration, rapid application 
development, and more. You get a dear picture of where 
the technology is — and where it's headed. SD '95 
delivers all the information, tools, and business 
contacts you need to thrive in today's challenging 
development world. 

Don't miss out. Bring your vision to SD '95. 
And leave with the tools to make it a reality. 
For more information, call C800) 441-8826, or <415) 688- 
4345 for fax-back info, ore-mail us at sd95west@mfi.com. 


Software Development '95. February 13-17, Moscone Convention Center. San Francisco, CA 

250 CLASSES * 2S0 VENDORS + IE. 000 DEVELOPMENT PROFESSIONALS 


OS2D 














Toolbars are becoming the norm for all types of applications. This article presents a custom Presentation 
Manager control that saves developers a large amount of the effort and code maintenance required 
to support a toolbar. By MARK McMILLAN, GENNARO CUOMO,, JURG VONKANEL, and 
GUILLAUME LE STUM 


A User-Customizable 
Toolbar Control 


r he graphical toolbar is a popular 
concept used to improve the us¬ 
ability of graphical-user-inter- 
face-based applications. As applications 
suffer from expanding "featuritis/' search¬ 
ing for commonly used functions in a 
text-based menu bar can become quite 
tedious. A toolbar gives a user the abil¬ 
ity to bypass the text menu bar and have 
direct access to the most commonly 
used functions. Its graphical and in¬ 
tuitive visual appearance gives the appli¬ 
cation a sophisticated look and feel. Tool¬ 
bars have almost become the norm for 
even moderately complex applications. 

For the Presentation Manager devel¬ 
oper looking to provide this type of 
function, the task is daunting, since 
Presentation Manager contains no na¬ 
tive support for this kind of graphical 
control. The graphical requirements 
alone are a significant programming ef¬ 
fort. Add to that the code for user cus¬ 
tomization of the toolbar, and it adds up 
to a significant project in itself. All of 
this is overhead to the essential func¬ 
tions of the application. 

We present here a custom Pre¬ 
sentation Manager control that sports a 
number of different styles and arrange¬ 
ments of bitmaps to produce a variety of 
visual effects {as illustrated in Figure 1), 
By using this control, a Presentation 


Manager developer is saved the large 
development effort and code mainte¬ 
nance required to support a toolbar. 
This, in turn, allows more development 
resource for basic application function¬ 
ality and a shortened development 
cycle. Mo expensive graphical user inter¬ 
face builder tools or class libraries are 
required—just an OS/2 2.x compiler, the 
standard OS/2 toolkit, and the run-time 
code supplied in the package. The run¬ 
time code may be statically or dynami¬ 
cally linked. 

The control was originally con¬ 
ceived at the IBM York town Research 
laboratory by Gennaro Cuomo and ]urg 
von Kanel for use in EFM (the OS/2 en¬ 
hanced system editor). Its value for gen¬ 
eral application development was recog¬ 
nized, and the design was generalized 
into a prepackaged custom Presentation 
Manager control, with subsequent de¬ 
velopment contributions from 
Guillaume Le Stum, John Ponzo, Alan 
Warren, and Alex Bertrand. Mark 
McMillan of IBM Research Triangle Park 
developed the sample code and frame 
control utility functions and initiated 
improvements in the architecture. An 
earlier version of this control appears on 
the OS/2 Developer Connection CD 
Volume 4. The current version contains 
many improvements and new samples. 
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Aside from the good graphical pre¬ 
sentation, the most significant features 
of this control are the easy user cus¬ 
tomization methods it provides (thus 
the name, UCMenus). Customizing a 
UCMenu is made easy for the user by 
extensive use of direct manipulation 
techniques. For example, to delete an 
item from the toolbar, the user can drag 
the item to the system shredder. Re¬ 
ordering the items is as easy as dragging 
the item to a new position and dropping 
it. Table 1 shows all the direct manipula¬ 
tion functions provided by UCMenus. 

Clicking the context mouse button 
on a UCMenus toolbar pops up a con¬ 


text menu that allows the toolbar styles 
to be changed and items to be added 
and deleted (as shown in Figure 2). The 
control has built-in dialogues that allow 
the user to change the bitmaps, text, and 
application function associated with any 
menu item. Figure 3 shows the notebook 
used to associate the menu item with an 
application function. 

All customization is encapsulated in 
the UCMenu control itself. The control 
and the application cooperate via mes¬ 
sages to provide application-specific in¬ 
formation during customization. Using 
the built-in customization methods the 
user can: 



Figure t A standard frame window with four UCMenu toolbars. 
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• Modify styles related to visual 
effects 

• Add and delete items and sub¬ 
menu items 

• Replace bitmaps with .BMP files 
or application-supplied bitmaps 

• Edit the text under the bitmap 

• Associate application functions 
with menu items (the applica¬ 
tion supplying the list of valid 
functions) 

• Move/copy menu items within 
a menu or between menus 

• Restore the entire menu to an 


application-defined default 
state. 

The application can restrict 
what customization functions are 
allowed, which we will discuss 
later in this article. 

UCMENU STYLES 

Like many Presentation Manager 
controls, the visual appearance of a 
UCMenu can be modified through 
the use of "style" flags. Figure 1 
shows an application with toolbars 
of several different styles. 


UCMenu toolbars can have a verti¬ 
cal, horizontal, or matrix layout. 
The bitmap items can be drawn 
with or without three-dimensional 
frames, text underneath, and fixed 
or automatic sizing. Individual 
items can be highlighted with a 
check-mark attribute and are 
drawn with thick dark borders. 
Background colors of the menu 
items and empty toolbar spaces 
can also be controlled. When re¬ 
quired by window size, scrollbar 
controls will automatically appear 
at each end of the toolbar. 


Edit item... 
Create item... 
Delete item 



iPl UC Menus Sam 

File Edit View 


Change style... 
Load Default 
Import... 
Export... 


Grid 


Ruli 


Figure 2. The built-in UCMenus context menu. 



Figure 3. The built-in UCMenus customization notebook. 


UCMENU PROGRAMMING CONCEPTS 

Several key concepts need to be 
understood to make effective use 
of UCMenu controls in an applica¬ 
tion program. As its name implies, 
the basic paradigm of a UCMenu 
control is that of a normal 
Presentation Manager text menu; 
the control contains selectable 
items, submenus, separators, item 
attributes, and so on. (The current 
implementation is limited to a sin¬ 
gle level of submenus.) As we will 
see, the developer's view of this 
control is also similar to that of a 
Presentation Manager menu con¬ 
trol. This similarity is by design 
and allows anyone familiar with 
Presentation Manager menus to 
grasp the terminology, concepts, 
and messages involved with 
UCMenu controls. It is important 
to recognize that there are some 
key differences, many of which we 
will cover in this article. 

The UCMenu control uses 
many of the same menu-related 
messages and data structures as its 
Presentation Manager menu coun¬ 
terpart. (In fact, a real Presentation 
Manager menu is used "under the 
covers" of the UCMenu control, 
but that is hidden from the appli¬ 
cation.) For example, a MM.QUERYITEM 
message can be sent to the 
UCMenu window to obtain a MENU- 
ITEM structure that describes a par¬ 
ticular item in the menu. The ap- 
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plication will receive all the stan¬ 
dard Presentation Manager menu 
notification messages except 
VMRAYITEM and WM.MEASUREITEH, 
which are used internally by the 
UCMenu, and YM_CQHMAND, which is 
replaced with a YM_C0NTROL message. 

Because of its added visual 
and interactive complexity, the 
standard Presentation Manager 
menu structures and messages are 
not sufficient to implement a cus¬ 
tomizable graphical menu bar. 
Thus, UCMenus adds another 
layer of messages and data struc¬ 
tures on top of the Presentation 
Manager menu architecture. It is 
important to understand the new 
concepts that UCMenus brings to 
the existing menu architecture and 
how the Presentation Manager 
menu architecture has been ex¬ 
tended to accommodate them. 

UCMenu Action Strings. One of the 

most important new concepts that 
UCMenus brings to a menu is that 
of actions. An action is a textual de¬ 
scription of the function assigned 
to a particular menu item. It is an 
arbitrary string defined by the ap¬ 
plication and seen by the user 
when customizing a UCMenu. It is 
usually a short two- or three-word 
phrase that defines the application- 
specific function the menu item is 
to perform when selected. For ex¬ 
ample, a text editor might define 
action strings like: 

"Copy to Clipboard" 

"Paste from Clipboard" 

"Left Justify" 

"Select Fonts" 

When creating a new UCMenu 
item or modifying an existing item, 
a user will select from a list of ac¬ 
tions supplied by the application. 

Applications that use Pre¬ 
sentation Manager menus often as¬ 
sociate specific application func¬ 
tions with specific item IDs. Figure 
4 shows the typical processing of a 


yw_C0HHAND message from a Pre¬ 
sentation Manager menu control. 
The application function selected 
in the switch statement is based on 
the item ID supplied by the menu 
control in mpl. 

For a UCMenu control, the 
item IDs are arbitrary and can 
change during execution of the 
program. An application cannot 
know ahead of time what the item 
IDs are going to be for any particu¬ 
lar menu item. To understand why, 
consider what happens when a 
user adds a new menu item to an 
existing UCMenu toolbar. The 
UCMenu control supplies all the 
user interface necessary for the 
user to choose a bitmap, text, and 
an application-specific action for 
the new item. When the new item 
is added to the menu, the UCMenu 
control will choose an arbitrary 
item ID that is unique throughout 
the menu and all submenus. 
Likewise, items can be moved and 
copied between UCMenu toolbars. 
The resulting (new) menu items 
are assigned arbitrary IDs that do 
not conflict with any existing 
items. 

The implication for the appli¬ 
cation is that it cannot depend on 
using item IDs to determine what 


function was selected on a 
UCMenu toolbar. Instead, the ap¬ 
plication must use the action asso¬ 
ciated with the menu item to deter- 
mine what function has been 
selected. A UCMenu control will 
send a WH_CONTROL message with a 
notification code of tfCNJT EM 5 ELECTED 
when an item is selected. The ap¬ 
plication will not receive a WM_C0fl~ 
HAND message from a UCMenu 
control. 

The application must associate 
the action string of the selected 
menu item with an application 
function. The toolkit sample pro¬ 
gram (SAMP1.C) uses a table that 
maps action strings to fixed ID val¬ 
ues. The action of the selected item 
is looked up in the table and then a 
simple switch can be used to select 
the correct application function in 
a manner similar to the original 
WW_C0MMAND processing in Figure 4. 
The ID values chosen for the table 
purposefully match the fixed item 
IDs used in the applications stan¬ 
dard Presentation Manager menu 
bar (the application has both 
UCMenu toolbars and a standard 
Presentation Manager menu bar). 
Thus, the same switch can be used 
to process WH_CDtfHAND messages from 
the Presentation Manager menu 


case VM_COWMAND: 

switch (SH0RT1FROMMP(mp2)) { 
case CMDSRCJBIU: 
switch (SHQRT1FR0MHP(mpl)) { 
case XD.FILESAVE: 

// process file save 
break; 

case ID^FHEDPEN: 

// process file open 
break; 

} 

case CMD5RC_PUSHBUTTON: 

// process all pushbuttons 

} 

break; 


/* Msg from a menu control */ 
/* File->Save item selected */ 

/* Fiie~>0pen item selected */ 


/* end of ^COMMAND */ 


Figure 4 . Processing a typical Presentation Manager menu selection. 
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UCMITEM #Ite«Data; 

USHORT ItemD; 
int i; 

tdefine MXJCTDMS 4 

struct { /* Table to map action strings to fixed IDs */ 

USHORT CmdlD; /* Unique ID for each menu Item */ 

PSZ Action; /* Unique 'action' string */ 

> IctionTabletHU JCHONS] = { 

{ID.CaPY, "Copy to Clipboard" }, 

(ID.PISTE, "Paste from Clipboard" } t 

{ID.LJUSTIfY, "Left Justify" } # 

{ID.FQNTS, "Select Fonts" }, 

>; 

case WM.COMMANO: 

if (SH0RT1FR0MMP(mp2) == CMDSRC.MENU) { /* From the PM menu */ 

/* IDs of PM menu items are fixed ID_KXXX values */ 

ItemD = SHDRTlFRQHMP(mpl); /* Extract item ID */ 

WinSendMsg(hwnd, WM.USER+l, /* Send myself msg to do it */ 

MPFROMSHORTatemlD), OL); 

} 


case ^CONTROL: 

if { (SHORT1FR0MMP(mpl) == ID.TQDLBIR) 

(SH0RT2FR0KHP(mpl) == UCN.ITEMSELECTED)) { 
if (ItemData->pszAction == NULL) /* Ignore if no action */ 
return 0; 

/* Lookup action of this item and map to fixed ID,)U£XX value */ 
/* then send myself a message to process it* */ 

for (i=0; KMAX.ACTIDNS; i++) { 
if (!strcmpi{ActionTable.Action[i], ItemData->pszlction)) { 
WinSendMsgChwnd, WM.USER+l, 

MPFROMSKQRT(IctionTable * CmdID) # OL); 

return 0; 

} 

> 

VinHessageBox(.terror, action not recognized,,,); 
return 0; 

} 


case VH_USER+i; /* Process selections from any menu */ 
switch (SH0RT1FftOMMPCmpl>) { 

case ID.COPY: //do clipboard copy 

break; 

case ISD.PISIE: //do clipboard paste 

break; 

case ID.LJUSTIFY: // do justification 
break; 

case ID^FONTS: // do font selection 

break; 

} 

return 0; 


Figure 5 Method to combine Presentation Manager and UCMenu selection processing. 


and WH.CONTROL messages from the 
UCMenus, This reduces code size 
and keeps application-specific 
functions from being duplicated. 
The combined method for process¬ 
ing both Presentation Manager 
menu and UCMenu selections is 
shown in Figure 5. 

A list of all UCMenu-related 
messages is shown in Figure 6. The 
messages are grouped by messages 
the UCMenu control sends to 
query the application for informa¬ 
tion (WM_C0NTRQL), messages sent to 
notify the application of significant 
events (WM_C0NTRGL), and messages 
sent by the application to the 
UCMenu to query or set various 
values (UCMENU,*). 

UCMENUS DATA STRUCTURES 

Two primary data structures are 
related to UCMenu controls. 
Associated with each UCMenu 
window is a set of data that de¬ 
scribes various aspects of the 
overall toolbar appearance and 
behavior. This includes informa¬ 
tion such as style flags, menu col¬ 
ors, and text font. This is the 
UCMINFO structure shown in Figure 
7, It is filled in by the application 
and used during creation of a 
UCMenu control. 

Associated with each item of 
the menu are two linked data 
structures, as shown in Figure 8. 
The first is the standard 
Presentation Manager MENUITEM 
structure. That structure contains 
an "item handle" that is generally 
reserved for application use. A 
UCMenu uses the item handle to 
point to a UCMITEM structure, which 
provides UCMenu-specific item in- 
formation. In effect, the MENUITEM 
structure is extended for UCMenu- 
specific data. It should be noted 
that any of the string pointers in 
the UCMITEM structure can be null. 
These data structures are used 
extensively in the processing of 
messages to and from the 
UCMenu control. 
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Checkable Menu Items. The fact that 
a UCMenu can be extensively cus¬ 
tomized by the user has some im¬ 
portant implications for applica¬ 
tions with "checkable" style menu 
items. Like a Presentation Manager 
menu, any item in a UCMenu can 
be checked simply by setting the 
MIA.CHECKED attribute for that item. A 
menu item should be checkable if 
the action associated with it repre¬ 
sents the toggling of some applica¬ 
tion state. A checked menu item is 
indicated in a UCMenu by draw¬ 
ing a thick border around it. 

When a UCMenu item is cre¬ 
ated by the user, the MIA.CHECKED at¬ 
tribute is not set. Thus, if the action 
selected by the user for the new 
item is a toggle function, the appli¬ 
cation should update the current 
state of the item with the current 
state of the application. 

Likewise, when a menu item is 
modified and assigned a new ac¬ 
tion, the current attributes are not 
changed. If the new action is a tog¬ 
gle function, the item attribute 
must be updated to reflect the cur¬ 
rent application state. If the action 
is not a toggle function, the 
MIA.CHECKED attribute should be 
cleared since the previous action 
may have been checked. 

The UCMenu control will send 
a VM.CONTROL message with a notifi¬ 
cation code of UCN.ADDEDITEM or 
UCN_ACTION when a new item is 
added or an action is changed. 
When these messages are received, 
the application must examine the 
new action and set or clear the 
MIA.CHECKED attribute. The code in 
Figure 9 shows the processing of 
this message. Note that we have 
expanded the table used in Figure 
5, which maps actions to fixed IDs, 
adding flags to determine if a par¬ 
ticular action is supposed to be 
checkable and to track its check 
state. 

When the application is noti¬ 
fied of a selection on a checkable 
UCMenu item, it must toggle the 


WM.CONTROL notification codes (UCMenu queries application for info) 

UCN.QRYTEMPLATEID 

Return resource ID of default menu template 

UCN.QRYTEMPLATEMODULE 

Return module handle of resource 

UCN.QRYRESBMP 

Return list of all bitmap resource IDs 

UCN.QRYACTIONLIST 

Send UCMENU.INSERTACTION for each supported 


action, then UCMENU.ACTIONSINSERTED 

VN.CONTROL notification codes (UCMenu notifies application of events) 

UCN.ITEMSELECTED 

A UCMenu item was selected 

UCN.CMITEM 

A context menu item added by app selected 

UCN.SIZE,STYLE.FONT,COLOR 

A UCMenu style or attribute has changed 

UCN.ADDEDITEM 

A new item was added to the menu 

UCN.DELETEDITEH 

An item was deleted from the menu 

UCN.BITMAP 

The bitmap of an item was changed 

UCN.TEXT 

The text of an item was changed 

UCMCTION 

The action string of an item was changed 

UCN.HLP.* 

Help requested on customization dialog, 


occurs only if style UCS.CUSTOMHLP 

UCN.MOUSEMOVE 

The mouse moved on an item 

UCMenu messages (from application to UCMenu control) 

UCMENU.ADDITEMSTOCM 

Add items to popup context menu 

UCHENU.INSERTICTION 

Response to UCN.QRYACTIONLIST 

UCMENU.ACTIONSINSERTED 

Signifies end of action list 

UCMENU.SETBGCOLOR 

Set menu and item background colors 

UCMENU.SETSTYLE 

Set menu style (UCS_* flags) 

UCMENU.UPDATE 

Update menu after style changes 

UCMENU JJUERYCOLOR 

Query menu bkgd and item bkgd colors 

UCMENU.QUERYFONT 

Query current menu font (text under bmps) 

UCMENU.QUERYFORCEDSIZE 

Query cx.cy if UCS.FORCEDSIZE style 

UCMENU.QUERYSIZE 

Query cx.cy for full menu display 

UCMENU JJUERYSTYLE 

Query menu style (UCS_* flags) 

UCMENU.QUERYUCMINFO 

Query complete menu create structure 

UCMENU.QUERYVERSION 

Query version number of UCMenus 

Figure 6. Summary of UCMenu messages. 

typedef struct { 


ULONG cb; 

// Size of this structure 

HMODULE hModule; 

// Module where the bitmaps are 

USHORT NbOfCols; 

// Number of columns in matrix style 

USHORT NbOfRovs; 

// Number of rows in matrix style 

PSZ pszBitmapSea rchPath; 

// Path(s) to search for bitmap files 

PSZ pszDefaultBitmap; 

// Bitmap to use if bitmap specified for 


// a menu item can't be loaded. 

ULONG Style; 

// Style of item (UCS.XXXX flags) 

ULONG cx; 

// Fixed item size if UCS.FORCESIZE 

ULONG cy; 

// Fixed item size if UCS.FORCESIZE 

LONG BgBmp ; 

// RGB of bitmap color to be replaced 


// with ItemBgColor. 

LONG BgColor; 

// RGB of UCMenu background (no items) 

LONG ItemBgColor; 

// RGB of UCMenu items background 

PSZ pszFontNameSize; 

// Font of the UCMenu or NULL for default 

} UCMINFO, *PUCMINF0; 



Figure 7 . UCMIlilFO structure describing general characteristics of a UCMenu. 
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check state. In a standard Pre¬ 
sentation Manager menu, it is suf¬ 
ficient to toggle the state of just the 


menu item selected. Since a 
UCMenu may have the same (tog¬ 
gle) action on different items in the 


same menu, the check state of all 
items with the toggle action must 
be updated. 

This function has been incor¬ 
porated into the UCMenu API set 
with the function UCHenuSet- 
ActionAttrO. This API will set the 
attributes of all items in the 
UCMenu with the specified action 
string. If the application has multi¬ 
ple UCMenu toolbars, all must be 
updated since the action may exist 
in any of them. 

Customization Messages. Easy cus¬ 
tomization of the toolbar is one of 
the most useful and powerful fea¬ 
tures of this control. It gives the 



Figure 8. UCMenu item data structures. 


Move menu items 

Drag and drop menu items from one position to another. New position 
will be insertion point nearest the mouse cursor when the item is dropped. 
MI$_$PACER items can also be moved. Items may be moved from one toolbar 
to another. 

Copy menu items 

Drag and drop menu items with the Ctrl key pressed. Items may be 
copied from one toolbar to another. 

Copy to submenu 

Drag menu item with Alt key pressed and drop on another menu item. If 
the target item is not a submenu it will be changed to be one. The dropped 
item is inserted after the last item already in the submenu. Submenu items 
can be copied from one toolbar to another. 

Delete menu items 

Drag menu item to system shredder. 

Create new items 

Drag .BMP file type from desktop or drives folder onto a toolbar. A new 
item with the supplied bitmap will be created. The item will not have any 
text or action associated with it until provided with the context menu 'Edit 
item' option. 

Render bitmap to tile 

A menu item that has file-supplied bitmap (the bitmap specification is a 
file name, not an application resource) can be dragged to the OS/2 desk¬ 
top or a folder to create a .BMP file. The bitmap can also be dropped on the 
OS/2 Icon Editor desktop object to open and edit the source bitmap file. 

Change colors 

A color can be dragged from the system color palette onto the toolbar 
background or the item background. All items will have the same back¬ 
ground color. 

Change font 

A font can be dragged from the system font palette onto the toolbar. The 
dropped font will be used for the text under the bitmaps. 

Items can also be created, deleted, and edited with the context menu, which may be displayed by positioning the cur¬ 
sor on a menu item and pressing the right mouse button. 


Table t. Direct manipulation capabilities of UCMenu toolbars. 
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user complete flexibility to add 
and delete menu items, rearrange 
the order, create submenus, and 
move and copy items between 
toolbars. Encapsulation of these 
functions into the UCMenu control 
means that there is very little ap¬ 
plication code required to support 
customization* 

Although most of the cus¬ 
tomization function is encapsu¬ 
lated in the control itself, the ap¬ 
plication must respond to several 
messages for customization to 
work properly. The UCMenu con¬ 
trol will send WM.CONTROL messages 
to its owner when it needs certain 
types of information to present 
on the customization notebook 
dialogues* The WM.CQNTRQL notifica¬ 
tion codes for customization are 
as follows: 

* UCMRYDEFAULTID: This is sent 
when the user selects the Load 
default context menu item to re¬ 
store the entire UCMenu to its 
default configuration. The appli¬ 
cation responds by supplying 
the resource ID of the menu tem¬ 
plate to be loaded* 

* UCN.QRYTEMPLATEMDDULE: This is also 
sent when the Load default con¬ 
text menu item is selected. The 
application must supply the 
handle of the module in which 
the tICN.QRYOEFAULTXD resource is to 
be found. 

* UCN.QRYRESBMP: This message is 
sent when the user wants to dis¬ 
play a list of application-sup¬ 
plied bitmaps from which to 
choose. The application must al¬ 
locate and construct an array of 
bitmap resource IDs. 

* UCN.qRYACnONLIST: This message is 
sent when the user has re¬ 
quested a list of actions from 
which to choose. The application 
responds by sending a series of 
UCHEN4I_INSERTACTION messages, 
each with a pointer to an action 
string and descriptive help text 
After the last action has been in¬ 
serted, the application must 


WENUITEM Menultem; A Std PH menu item data */ 

UCMITEK *ItemOata; A UCMenu item data ♦/ 

int i; 

idefine MAX .ACTIONS 4 

struct { A Table to map actions and track check states */ 


USHQRT CmdlD; A Unique ID for each menu item */ 

PSZ Action; A Unique 'action' string */ 

BOOL Checkable; A Is this item checkable V 

USHORT CheckStatus; A Zero (not checked) or MIA.CHECKED */ 

} kUonTable [HA MOTIONS] = { 

{ID.COPY, "Copy to Clipboard" , FALSE, 0}, 

{ID.PASTE, "Paste from Clipboard 1 ' , FALSE* 0}, 

{ID.LJUSTIFY, "Left Justify" , FALSE* 0>, 


{^INSERT, "Toggle Insert Mode" , TRUE* Oh //<“Checkable 

>; 

case VM.CQNTROL: 

if { (SHQRTlFROHKP(mpl) BJQ0LBIR1) II A Hsg from any toolbar */ 
(SHORTlFRQHHP(mpl) » ID.TOOLBAR2)) 
switch (SHORTFROMHP(mp2)> { A Notify code */ 

UCN.ADDEDIIEH: A New item */ 

UCN.ACTION: A Cbnged action */ 


fa If an item is added or its Action changed check */ 
A if the selected action a checkable item. If so */ 
A we must set the current check state* */ 
A mpl^MenuB* Notify Code mp2*XteinID */ 


if (IWinSendHsg (VinWindowFromID (hwnd, SHQR1FR0MMP (mpl)h 
HM.QUERYITEM * 

MPFR0H2SHQRT (SHORTIFROMMP (mp2), TRUE)* 
HPFROMP (fcHenuIlem))) 

return 0; 

fa Check that the UCTTEH->Action string pointers are OK */ 
ItemData = (UCHITEM *)(Menultem.hltem); 
if (ItemData==N U LLH A NOLE) 
return 0; 

if (ItemOata->pszAction==NULL)) 
return 0; 


A Lookup action of this item in action table */ 
for 0-0; i<HAX.ACTIONS; i++) 

if (fstrcmpKActionlable*Action[i], ItemData->p$zAction)} { 

A If action is supposed to be checkable, set its */ 

A check state to the current application state* */ 
if (ActionTablefi],Checkable) { 

WinSendflsg{WinWindowFromID(hwnd, SH0RTiFR0MMP{mpl))* 
MM.SETTTEMATTR* 

MPFR0M25HDRT)SHORTIFROMMP(mp2)* TRUI), 

MPFR0H2SHQRT(MIA_CHECKE0,ItemList[i].CheckStatus)); 

> 

else { A Action is not checkable, remove any check mark */ 
WinSendHsg(WinWindowFromID(hwnd t SH0RT1FR0MMP(mpl)}, 
MH.SEITTEHATTR* 

HPFROM2SKDRT<SHORT1FR0MMP(mp2), TRUE)* 
HPFR0M2SHDRT(MIA.CHECKED 1 -MIA.CHECKE0}); 

} fa if checkable */ 

> A if action found in table */ 

} fa switch on notify code */ 


Figure 9 . Setting "checked" attribute on added and modified UCMenu items. 
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send UCHENU_ ACTIGNSXNSERTED to in¬ 
dicate the list is complete. 

* BCN_HLP_*: This is a set of mes¬ 
sages sent when the UCS_CUSTOMHLP 
menu style is used and the user 
requests help on a customization 
dialogue. By default, the 
UCMenu control will supply the 
needed help text. 

The handling of all these mes¬ 
sages is demonstrated in the 
SAMP2.C sample program. 


Moving Menu Items 


Table 2 UCMenu customization style flags. 


CONTROL OF CUSTOMIZATION 

The highly flexible customization 
built in to the UCMenu control 
may not be desirable for all appli¬ 
cations or situations. For example, 
the ability to move items from one 
menu to another within an appli¬ 
cation may not make semantic 
sense. An application with multi¬ 
ple windows performing different 
functions may not want to allow 
the user to drag items from the 


toolbar in one window to the tool¬ 
bar in another. The result might be 
actions that make no sense in the 
context of the window. The appli¬ 
cation may also want to provide its 
own customization methods to re¬ 
place or supplement those of 
UCMenus, 

By default, all the direct ma¬ 
nipulations shown in Table 1 and 
all the context menu options 
shown in Figure 2 are allowed. 
Various style flags (UCS_*) can be 
used by the application to control 
which direct manipulation and 
context menu functions are sup¬ 
ported for that instance of the 
menu. At the extreme, the applica¬ 
tion can set a style of UC$_$TATIC to 
prevent any customization at all. 
This style will disable all direct 
manipulation functions and the 
context menu. Other style flags 
allow selective disabling of specific 
customization functions, such as 
disabling drag-and-drop between 
menus (but allowing it within a 
menu), disabling drops to the sys¬ 
tem shredder, removing the "Edit 
item..," context menu option, and 
so on. Table 2 summarizes the cus¬ 
tomization style flags. 

An application can also supply 
its own customization functions 
via the UCMenu context menu. By 
sending the control a UCMENU_AD- 
DIT EM STOCK message, the application 
can add its own options to the con¬ 
text menu. The UCMenu control 
will send a WM_CQNTRQL message with 
a notify code of UCN^CMITEM when 
such an option is selected. A sam¬ 
ple of adding an application cus¬ 
tomization function to the context 
menu is shown in Figure 10. 

CREATING A UCMENU CONTROL 

Conceptually, creating a UCMenu 
control is the same as creating a 
Presentation Manager menu con¬ 
trol. The menu structure and items 
are defined in textual form in a re¬ 
source file (.RC) using MENU, MENUITEM, 
and SUBMENU statements. The re- 


UCS_N0_ DM _M_TQ_0THER 
UASJO.DMJLFROHJTHER 

UCS_NQ_ DM_M_FROM _INSIDE 


Disable drag-move of items to another UCMenu 
Disable drop-move of items from another 
UCMenu 

Disable drag-drop move (rearrangement) of 
items inside this UCMenu 


Copying Menu Items (CTRL key drag/drop) 


UCS_ N0_ DM _C_T0_ OTHER 
UCS_ N0_ D M_C_ FROM.OTHER 

UCSjOJM_C_FRQM_INSIDE 

UCSJDJMJlt 


Disable drag-copy of items to another UCMenu 
Disable drop-copy of items from another 
UCMenu 

Disable drag-drop move (rearrangement) of 
items inside this UCMenu 
Disable use of ALT key to copy items to 
submenus 


Desktop Interaction 

UC$_N0_DM_DISCARD 

UCSJO.DMJENDERJOJMP 
UCS_ NO,DM.RENDER_ FROM _BH P 
Context Menu Control 

ucs_no,cmenu_styie 

UCSJO,CM_HENU_IHPDRT 
UCS_ ND_CM_M EN U _ EXPORT 
UCS_ NQ_ H E NU_ QEf AULT 

UCS_ NQ„ CfCXTEM_CRE A TE 

UGJO_CW.ITEM_DELETE 

UCSJQ_CM_ITE!UDTT 

Combination Styles 
UCSJO.DM 
UCS_N0_CM 
UCS^STATIC 


Disable drag of items to system shredder to 
delete them 

Disable drag of items to desktop to create .BMP 
files 

Disable drop of .BMP files to create new items 


Remove "Change style..." option from context 
menu 

Remove "Import..." option from context menu 
Remove "Export..." option from context menu 
Remove "Load default" option from context 
menu 

Remove "Create item..." option from context 
menu 

Remove "Delete item" option from context menu 
Remove "Edit item..." option from context menu 


Disable all direct manipulation 
Disable context menu 

Disable all direct manipulation and context 
menu 
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CMITEMS CMItem; /♦ Describes one context menu item */ 

static HwndUCM; /♦ Handle of UCMenu window ♦/ 



case YM.INITDLG: (or VM.CREATE): 

//...after UCMenu is created and handle is in hwndUCM... 

/♦ Add items to UCM context menu (we just have one) ♦/ 
CMItem.ID = ID.MYCUTOMZATION; 

CMItem.pszItemText = "Reset style"; 

WinSendMsg(hwndUCM, UCMENU.ADDITEMSTOCM, 

MPFROMLONG(IL), MPFRONP(ftCMItem)); 


case WM.CONTROL: 

if ((SHORTlFROMMP(mpl)=ID_TOOLBAR) Ml // From the toolbar menu 
(SH0RT2FR0MMP(mpl)=UCN.CMITEM)) { // Our context option 

if (SHORTlFROMMP(mpl) = ID.MYCUSTOMIZAnON) { 

/* Reset style of the menu to default. To be complete, */ 

/* this should also reset colors and fonts in case they */ 

/* were changed via drop from system palettes. */ 

WinSendMsg(hwndUCM, UCMENU.SETSTYLE, 

MPFROMLONG(UCS_FRAMEDIUCS.CHNGBMPICUSTOMHLP), 

MPFR0M2SH0RT(0,0)); 


> 


} 


Figure 10. Adding an option to the UCMenu context menu. 


source file is compiled with the re¬ 
source compiler into binary re¬ 
source format and appended to the 
application executable (or a DLL). 
The application calls an API to read 
the binary resource and create the 
visual Presentation Manager win¬ 
dows and underlying data struc¬ 
tures. Finally, the window is placed 
and sized on a parent window. 

Resource Files. The textual resource 
file specifies the complete structure 
of the menu and the contents of 
the menu items. However, the MENU- 
ITEM resource statement does not 
have the syntactic flexibility to 
allow complete specification of all 
the data associated with a UC¬ 
Menu item. Therefore, the text 
field of the MENUITEM statement is in¬ 
terpreted to contain four extra 
fields of information not found on 
standard Presentation Manager 
menu items: bitmap specification, 
action string, parameter string, and 
a data string. Each of these fields is 
separated by a single character de¬ 
fined as the first character of the 
string. A typical resource file for a 
UCMenu is shown in Figure 11. 

Some notes on UCMenu re¬ 
source files: 

• The menu item IDs specified in 
the resource file are arbitrary. 
Sequential numbering is used to 
help keep menu items unique 
but is not necessary. 

• A new menu item style 
MIS.SPACER is defined for 
UCMenus. It produces a blank 
space in the menu to separate 
menu items into groups. 

• The 'Data' field is not seen by the 
user and is for application use. 
Note that new items created by 
customization will have no 
'data' value. 

The UCMINFO Structure. To complete 
the process of creating a UCMenu, 
the application must construct a 
UCMINFO data structure (as shown in 
Figure 7) and fill in all the relevant 


fields. The RGB values of the struc¬ 
ture are used for color mapping 
the bitmap background pixels. 
UCMenus supplies a means for 
bitmap background pixels to be 
automatically mapped to the cur¬ 
rent UCMenu background color. 
The BgBmp value of UCMINFO tells 
UCMenus what background color 
was used in the design of the 
bitmaps. That color will be re¬ 
placed with the ItemBgColor before 
the bitmaps are displayed wher¬ 
ever that color appears in the 
bitmap. The ItemBgColor should be 
set to the SYSCLR.MENU color returned 
by WinQuerySysColorO. A different 
color may be specified in the 
BgColor field. This will be the color 
used wherever there are no items 
on the toolbar. 

Once the UCMINFO structure is 
filled in, the function 
UCMenuCreateFromTemplateO or 
UCMenuCreateFromResourceQ is called. 
The template version is used if the 
application has manually loaded a 


previously saved UCMenu tem¬ 
plate. The resource version will 
create a UCMenu from a menu 
template in the application's re¬ 
sources. The parameters are shown 
in Figure 12. The creation functions 
return two window handles. The 
function result is the window han¬ 
dle of interest for the application; 
the other may be ignored. 

PLACEMENT AND SIZING 
OF A UCMENU 

Toolbars are generally placed 
along one edge of the application 
window frame. Toolbars may be 
attached to the top, bottom, left, or 
right edge of the window. Figure 1 
shows a frame window with four 
toolbars, one on each edge of the 
frame. 

It is possible to simply place 
and size the toolbar into the client 
window of a standard Presentation 
Manager window. However, this 
simple approach introduces a lot of 
complexity when the application 
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BITMAP 6 

BITMAP 1 "open*bmp" 
SHUAR 2 "save.bmp" 
BITMAP 62 "styles,bmp" 
BITMAP 63 "bold,bmp" 
BITMAP 64 "italic,bmp" 
BITMAP 8 "help,bmp" 


/* Text strings are interpreted as: t/ 

f* *i 

/* "<c>Text<c>BitmapD<c>HctionStr<c>ParamStr<c>OataStr“ */ 

t* */ 

f* *bere <c> is any character that does not appear in the strings, */ 

/* */ 

/* Item style MIS_SPACER produces a gap in the menu bar, */ 


MENU HLCOKMANDBAR LDAOONCALL MOVEABLE DISCARDABLE 
BEGIN 

MENUITEH VWeB/6/to", 1, MIS.TEUT 

HENUITEM VDpen/l/Open File", 2, MISJHT 

MENUnEM "/Save/S/Save File", 3, MIS.TBT 

HEAJUITEM 4, MIS„SPACEft 

SUBMENU "/Styles/SS/Styles Submenu", 5, MISJHT 
BEGIN 

/* Use a different delim here so *e can use "/" in the strings */ 
MENUITEW "! Bold ! 63! Bold/Style 11 , 6, MISJEXT | M1S.CHECKABLE 

MENUITEM "! Italic! 64 !Italic/Style", 7, MISJEIT \ MIS_CHECKABLE 

END 

HENUITEM *\ 8, fdSjPACER 

HENUITEM H /ttelp/8/5how Help", 9, MISJEAT 

END 


Figure it Resource file statements fora UCMenu. 


must properly scale and paint the 
client window. If the frame win¬ 
dow is a dialogue, proper size and 
placement is even more complex 
since the application does not 
paint and there is no separate 
client window. 

The proper solution to toolbar 
placement is to make the toolbar a 
frame control , A frame control is a 
child of the frame window and par¬ 
ticipates in a special message proto¬ 
col. Standard frame controls include 
the title bar, scroll bars. Presentation 
Manager menu bar, min/max but¬ 
tons, and the system menu. The 
frame controls move and size with 
the frame window and keep proper 
position in the frame through the 
frame control messages. 

Making a window into a frame 
control requires a thorough know!- 
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edge of how Presentation Manager 
frame windows and message proto¬ 
cols work. Adding a frame control 
to a dialogue window is even more 
complex since it may require the 
movement of all the dialogue con¬ 
trols, All the functions necessary to 
make UCMenu windows into 
frame controls are supplied in a set 
of utility routines in the toolkit. 
These routines are not a formal part 
of the UCMenu control hut allow 
an application to easily place 
UCMenu controls along any edge 
of a frame or dialogue window. By 
using these utilities, an application 
can be completely removed from 
any sizing or positioning considera¬ 
tions for the toolbars. 

The frame control utilities con¬ 
sist of two functions: one to add a 
UCMenu to a frame or dialogue 
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window, the other to remove it. 
The UCHUtilsO functions are shown 
in Figure 13. The utilities support 
up to four toolbars per frame or di¬ 
alogue window (one each at the 
top, bottom, left, and right edges). 
By calling the add/remove frame 
control utilities, a toolbar can be 
toggled on and off. 

The UCMUtUsO functions encap¬ 
sulate all the complexity of frame 
control management, freeing the 
application from that task. With 
just a simple function call, the tool¬ 
bar can be positioned in the frame 
and will maintain its proper posi¬ 
tion as the frame is sized and 
moved. Source code for the utili¬ 
ties is provided in the toolkit. 

A DYNAMIC STATUS BAR 

One drawback to graphical menu 
bars is the cryptic nature of the in- 
formation presented. Even the 
most creative bitmaps can fail to 
convey the meaning of a function. 
Text under the bitmap, as allowed 
by UCMenus, helps the user 
quickly understand the functions 
on the toolbar. However, even that 
may not be enough for the casual 
user to grasp the meaning of a 
graphic menu item. 

A dynamic status bar can be 
implemented by the application to 
automatically show a description 
of each menu item as the mouse 
pointer is moved on the toolbar. To 
help the application implement 
this feature, a UCMenu with the 
UCS.PRQMPTING style will send UH,C0N- 
TRGL messages with a notify code of 
UCMQUSEMOVE when the pointer 
moves on the menu bar. The mes¬ 
sage supplies the menu item ID of 
the item under the mouse pointer. 
Using this item ID, the application 
can obtain the item data structures 
and determine the action string as¬ 
sociated with that item. The action 
string may be displayed directly, 
or it may be used to look up a 
more complete description for dis¬ 
play to the user. The SAMP2,C 



sample program uses the lookup 
method to display a longer de¬ 
scription of the menu items action. 

SA VING/RESTORING UCMENUS 

When an application with cus¬ 
tomizable menus is closed and 
restarted, the user expects the 
menus to resume their customized 
state. The application must save 
the complete state of the UCMenus 
when closing, including the menu 
attributes in the UCMINFO structure 
and the actual menu item structure 
(order of items, text, bitmaps, ac¬ 
tion strings, and so on). 

The UCMenus API provides 
several functions to aid the applica¬ 
tion in saving and restoring the cus¬ 
tomized state of UCMenu toolbars. 
The function UCHenuMakeTemplateQ 
will create a binary in-storage rep¬ 
resentation of the complete UC¬ 
Menu item structure. The binary 
image will include all text, 
bitmaps, action strings, and ar¬ 
rangements of menu items. The cor¬ 
responding APIs, UCWenuCreate- 
FronTemplateQ and UCMenuNew, create 
and replace UCMenu controls from 
an in-storage binary template. 

Figure 14 shows the processing 
of WH_SA VE APPLICATION for the 
SAMP2.C sample program. This 
sample has two UCMenu toolbars, 
but for brevity, the code for only 
one is shown* The UCMenu style, 
colors, and font, as well as the bi¬ 
nary templates, are stored in the 
application JNI file. During initial¬ 
ization, the styles, colors, font, and 
templates are read from the JNI 
file and are used to recreate the 
customized toolbars. 

SUMMARY 

The UCMenu control provides a 
powerful, slick-looking, and easy- 
to-use toolbar control for OS/2 
Presentation Manager applica¬ 
tions. The encapsulation of exten¬ 
sive customization capabilities 
gives application writers a power¬ 
ful, customizable toolbar with min¬ 


imal code. For the user, UCMenus 
provides an easy-to-use toolbar 
that is simple to customize with in¬ 
tuitive drag-and-drop and context 
menus. 

Examination of the SAMP2.C 
sample program shows how a typ¬ 


ical application might be struc¬ 
tured with respect to menus and 
menu selection processing* The 
sample shows the usage of most of 
the UCMenu-specific messages 
and fully implements all features 
of the UCMenu control. 


HVND UCMenuCreateFromResourcet // Returns handle of new toobar 


HUB 

hab, 

// PM anchor block of application 

HMD 

hParent, 

// Parent window 

HMD 

hOwner, 

// Owner window (reev messages) 

ULONG 

ulStyle, 

// CH$_VERT f BORZ(MATRIX plus VS_* flags 

LONG 

x, LONG y, 

// Position 

LONG 

ex, LONG cy, 

// Size 

HVND 

hlnsert&ehind, 

// 2 order 

ULONG 

ulID, 

// Window ID new toolbar is to have 

HHODULE 

hmodResource, 

// Resource module (NULLHANDLE for EAE) 

USHORT 

usKenuID, 

// 10 of menu in resources 

UCMINFO 

♦pUCHInfo, 

H Ptr to UCMINFO data 

HVND 

♦pbTextMenu) 

// (returned) PH menu handle (don't use) 

HVND UCMenuCreateFromTemplate( // Returns handle of new toobar 

hab 

hab. 

// PM anchor block of application 

HVND 

hParent, 

// Parent window 

HVND 

hQuner* 

// Owner window (reev messages) 

ULONG 

ulStyle, 

// CMSJEftT,HQRZ,MATRIX plus VS_* flags 

LONG 

x, LONG y. 

// Position 

LONG 

cx, LONG cy, 

ft Size 

HVND 

hlnsertBehind, 

// l order 

ULONG 

ulID, 

// Window ID new toolbar is to have 

VOID 

♦Template, 

If Ptr to instorage template 

UCMINFO 

♦pUCMInfo, 

// Ptr to UCMINFO data 

HVND 

♦phTextMenu) 

// (returned) PM menu handle {don't use) 

BOOL UCMenuNev{ 

// Update toolbar with new template 

HVND 

hwndUCMenu, 

// Toolbar window 

VOID 

♦Template) 

// Instorage template 

VOID *UCMenuMakeTemplate( 

// Make instorage template from toolbar 

HVND 

hundUCHenu, 

// Toolbar window handle 

LONG 

♦TemplateSize) 

// (return) Size of template 


Figure 72. Seciected UCMenu APIs. 

UCHUtils AddTo F rame( H VND hw ndF r ame, 

// Frame or dialog vindou 

HVND hvndUCMenu, 

// UCMenu to add to frame 

ULONG Placement) 

// Where to place toolbar: 

// UCMUTIL S _PLACE.TO P 
// UCMUTILS,PLAC£.B0TT0M 

H UCMUTILS.PLJICE^LEFT 
// UCMUTILS.PLUCE.RIGHT 

UCHUtilsRemoveFromFrame(RVNO hwndFrame,// Frame to remove toolbar 

HVND hvndUCMenu) 

// UCMenu to be removed 


figure 13. Frame control management utility functions. 
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II, 


/* Structure to easily save/restore menu information in INI file */ 
typedef struct { 


ULONG CmdStyle; 
ULONG CmdCx; 

ULONG CmdCy; 

ULONG CmdSize; 
ULONG CmdBgColor; 


/* Command menu style bits 
/* Forced size (x) 

/* Forced size (y) 

/* Size of menu template 
/* Toolbar background 


ULONG CmdltemBgColor; /* Item background 
char CmdFont[32]; /* Font name 

} IniDataStruct; 


BOOL ProfileFound = FALSE; 
UCMINFO UCMInit; 

PVOID CmdTemplate; 

HWND CommandBar; 


/* INI file existed 
/* UCMenu creation data 
/* Ptr to menu template 
/* UCMenu window handle 


♦/ 

♦/ 

♦/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

♦/ 

*/ 


WM.CREATE: // (or VM.INITDLG, if a dialog): 

/♦ If we have saved a previous UC menu configuration in the .INI 
/* file, restore its contents and style information. 

IniHandle = PrfOpenProfile(Hab, "myapp.ini"); 
if (IniHandle != NULLHANDLE) { 

/* If one value is here, they all should be */ 

ULValue = sizeof(IniDataStruct); 
if (PrfQueryProfileData(IniHandle, "APPNAME\ 

"IniData”, ilniData, ftULValue)) { 

CmdTemplate = malloc(IniData.CmdSize); 

PrfQueryProfileData(IniHandle, "APPNAME", "CmdTemplate", 
CmdTemplate, &(IniData.CmdSize)); 

ProfileFound = TRUE; 

> 

PrfQoseProfile(IniHandle); 

> 

// Initialize all fields of the UCMIinit structure here...then: 
if (ProfileFound) { /♦ Create menu from saved template ♦/ 

UCMInit.Style = IniData.CmdStyle; /* Restore menu style */ 

UCMInit.cx = IniData.CmdCx; /* Restore forced size */ 

UCMInit.cy = IniData.CmdCy; /♦ Restore forced size */ 

UCMInit.BgColor = IniData.CmdBgColor; /* Colors */ 

UCMInit.ItemBgColor = IniData.CmdltemBgColor; 

UCMInit.pszFontNameSize = IniData.CmdFont; /* Font */ 

CommandBar s UCMenuCreateFromTemplate(...CmdTemplate...); 
free(CmdTemplate); 

> 

else { /* Create menu from resource file */ 

CommandBar = UCMenuCreateFromResource(...ID.TOOLBAR...); 

} 


*/ 

*/ 



WM.SAVEAPPLICAnON: 

/♦ Create incore template representation of the menu */ 
CmdTemplate = UCMenuMakeTemplate(CommandBar, A(IniData.CmdSize)); 
/* Open INI file and save template and style info */ 

IniHandle = PrfOpenProfile(Hab, "myapp.ini"); 
if (IniHandle != NULLHANDLE) { 


Figure 14. Saving and restoring a customized toolbar in the application .INI file (continued on page 63). 
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PrfWriteProfileOata(IniHandle, "APPNAME", "CmdTemplate", 

CmdTemplate, IniOata. CmdSize); 

/* We must also save the style bits, size, colors, fonts. */ 

/* Colors and fonts can be modified via system palettes. */ 
WinSendMsg(CommandBar, UCMENU.QUERYUCMINFO, MPFROMP(ftUCMInit), OL); 
IniData.CmdStyle = UCMInit.Style; 

IniOata.CmdC x = UCMInit.c x; 

IniData.CmdCy = UCMInit.cy; 

IniData.CmdBgColor = UCMInit.BgColor; 

IniOata.CmdltemBgColor = UCMInit.ItemBgColor; 

if (UCMInit.pszFontNameSize != NULL) 
strcpy(IniOata.CmdFont, UCMInit.pszFontNameSize); 
else (IniOata.CmdFont)[0] = '\0'; 
UCMUtilsFreeUCMInfoStrings(feUCMInit); 

PrfWriteProfileOata(IniHandle, "APPNAME", "IniOata", ftlniOata, 
sizeof(IniOataStruct)); 
PrfQoseProfile(IniHandle); 

} 

UCMenuFree(CmdTemplate); 

UCMenuFree(QrTemplate); 
break; 



Figure 14. Saving and restoring a customized toolbar in the application INI file Icontinued from page 62). 
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This article provides a brief overview of things to keep in mind when developing applications for OS/2, 

By DIETER BABUTZKA 


An OS/2 Performance 
Primer 


O uring the development of a 
new application, performance 
isn't always given the attention 
it deserves, particularly in the early 
phases of a project. This article re¬ 
views some basic guidelines that 
should help improve your OS/2 appli¬ 
cation's performance. 

PROCESSES AND THREADS 

A large number of processes and 
threads in your application generate 
overhead from process and thread 
switches. It makes sense to use multiple 
processes and threads only when they 
can run independently or are used for 
protection reasons. Process switches con¬ 
sume more time than thread switches. 
Use multiple threads only if the applica¬ 
tion consists of parts that are able to run 
concurrently Multiple processes should 
be used to prevent accidental overwrit¬ 
ing of memory and to be completely in¬ 
dependent of other parts of the applica¬ 
tion (crash protection). 

FUNCTION CALLS 

Although it may be fashionable to create 
a lot of very small functions, this can 
lead to performance problems since 
there is a significant overhead for func¬ 
tion calling. It is important to avoid a 
high number of calls from 16-bit to 32- 


bit applications because this leads to a 
perceptible overhead. 

HOST OR LAN CALLS 

Most newly developed applications are 
not stand-alone but work in a client/ 
server environment. It is important to 
keep the number of interplatform calls 
to a minimum because every communi¬ 
cation step generates an overhead that 
leads to longer response times. 

MEMORY CONSUMPTION 

In a modem OS/2 environment, there is 
almost unlimited virtual storage avail¬ 
able for every application. But using a 
large amount of storage reduces not only 
the speed of your application but also the 
storage available for other applications, 
so their speed is also reduced. Tfy run¬ 
ning the code example in Figure 1 while 
running another application. YbiijTl no¬ 
tice that the whole system is much lesK 
responsive. Be careful! This program will 
use up to 40 MB of memory, and eventu¬ 
ally your swap drive will be full. 

DYNAMIC LINK LIBRARIES 

The use of DLLs makes a lot of sense be¬ 
cause the storage used for the whole 
system can be reduced. To reduce load¬ 
ing times, the number of DLLs should 
not be too large. We were able to reduce 
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startup time more then 10% after 
we reduced the number of DLLs 
from 20 to only one, 

DATA FILTERS AND DATA 
CONVERSION 

Sometimes much more data is 
transferred from a server to a client 


than is really used. This should be 
avoided by using data filters at the 
first possible point, usually on the 
server. Often, the data is converted 
many times before it reaches the 
user. Try to convert data only once. 
Following is a typical example of 
the usefulness of a data fitter. Let's 


say you work on an OS/2 machine 
with a host database as a server 
and want to get data from this 
database. The database should 
consist of a large number of data¬ 
base objects. If you want to get all 
objects where the object name 
starts with an A, you'll have 
mainly two options: 

* Get all objects from the host and 
look for all objects where the ob¬ 
ject name starts with an A. 

* Pass a filter to the host and cap¬ 
ture only these objects from the 
database where the object name 
starts with an A. 

Normally, the data has to be 
converted in the object format de¬ 
fined on the workstation. Try to 
keep this conversion as easy as pos¬ 
sible—meaning the organization of 
the objects on the workstation 
should not differ too much from the 
implementation on the host. 

APPLICATION BUILDERS 

An application builder makes 
sense in the development of large 
applications. For a small project, 
an application builder may not be 
advisable because it generates too 
much overhead. 

During the coding process, it is 
important to ensure the perfor¬ 
mance of an application (or of se¬ 
lected key sections) by using test 
scenarios. These scenarios should 
be defined during the design phase, 
and if possible, goals should also be 
specified. Attention should be paid 
to mainly two items. 

Path Length . Every developer 
should use a software performance 
analysis utility to measure the run 
time and the active time of a com¬ 
ponent, such as EXTRA. EXTRA is 
an abbreviation for the IBM 
C/C++ Execution Trace Analyzer. 
EXTRA is part of the IBM C Set++ 
compiler, but other performance 
analysis applications are also avail¬ 
able for many other compilers. 
With EXTRA, you can analyze the 



Figure t. Code example for an OS/2 application allocating a large amount of memory. 
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run time, the active time, the num¬ 
ber of calls, and who is called by 
whom. 

Figure 2 shows the statistical 
output of EXTRA for a test program. 
You'Ll get information about the ac¬ 
tive modules (EXEs and DLLs) and 
a lot of details about the function 
called during the test scenario. 

This is very important in com¬ 
plex systems coded in object-ori¬ 
ented programming languages. In 
this environment, it may not be 
known which calls occur and how 
often the various methods are 
called. 

Memory Consumption. Although in 
the OS/2 concept a lot of virtual 


memory is available for every ap¬ 
plication, you have to keep in 
mind that only a limited amount of 
real storage is available. We use the 
IBM SPM/2 2.0 product to check 
memory allocation. 

With THESEUS/2, which is 
part of SPM/2, you can determine 
the memory used in various alloca¬ 
tions (Decommitted, Committed, 
Accessed, Present, Swapped out). 
It can also be determined when an 
application allocates memory and 
does not free it again. This is not a 
real problem if the process to 
which this program belongs termi¬ 
nates. But if the program works as 
a server, which is designed to run 
continuously, it is very important 


to look for memory that needs to 
be freed. This can slow down per¬ 
formance dramatically. 

Figure 3 gives a short view 
about the actual memory division 
of all running programs. This is 
not the working set of the program 
but primarily a snapshot of the 
memory. 

Although EXTRA helps in 
finding application bottlenecks, it 
is important to measure perfor¬ 
mance test scenarios with accurate 
precision. To do this, it is impor¬ 
tant to measure with as little over¬ 
head as possible. EXTRA and other 
software tools normally operate on 
debugging and nonoptimized 
code, so loading and startup times 




Figure 2. Statistical output of EXTRA for a test program , 
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are higher than in production 
code. 

The tool we used to make this 
measurement accurately while 
generating little overhead was an 
IBM internal hardware tool. It is 
possible for IBM customers to bor¬ 
row this hardware to analyze ap¬ 
plications. Performance analysis is 
also available as an IBM service of¬ 
fering, which is available through 
the author. 

When using this tool, hooks 
are written to a special card and 
transferred to another machine for 
analysis after the test scenario has 
finished. 


Through the help of a software 
tool, hooks are included automati¬ 
cally at the beginning and the end 
of each function. After the execu¬ 
tion of the test scenario, informa¬ 
tion is available for each function, 
consisting of: 

* A trace listing showing when 
each function was called, who 
called it, and how long it was 
active 

* Statistics about the active and 
idle periods (for example, wait¬ 
ing for an event, host communi¬ 
cations, and so on) 

* Statistics about each observed 
function, how often it was 


called, time spent in each func¬ 
tion, and the overall run time. 

With this data, it is not difficult 
to find the bottlenecks of an appli¬ 
cation, although they still have to 
be fixed. 

Some additional considera¬ 
tions should be kept in mind: 

* Even a hardware test tool has 
some overhead—usually around 
2%. But this overhead is sub¬ 
tracted from its measurement, so 
its accuracy is very high. After 
the overhead is subtracted, the 
difference between instrumented 
and noninstrumented measure¬ 
ments is less than 1%. 



Figure 3 . Snapshot of the memory. 
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• No programmer likes to put 
hooks into his code for perfor¬ 
mance measurements. Therefore, 
an automatic instrumentation 
program is available that puts 
the hooks into the code without 
any manual interaction. These 
hooks are then written to the 
hardware for later analysis. 

The conclusion of our experi¬ 
ence is that it is important to look 
at the performance during the de¬ 
sign phase because it is hard to im¬ 
prove performance when coding is 
nearly complete. 

Dieter Babutzka has been with IBM 
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This article illustrates using the APL2programming language. By DAVID UEBTAG 


Interactive PM 
Programming 


S/2's Presentation Manager is 
large, powerful, and complex. 
Since it has nearly 600 Vi n and 
Gpi services, learning how to use it is a 
daunting task. However, many of the 
difficulties in learning Presentation 
Manager can be overcome by taking an 
interactive approach. 

When using a compiled language, 
the learning process requires that you 
have a working program before you can 
even start to work with OS/2 services. 
Obviously, it is a bit difficult to write a 
program using services you don't yet 
know how to use. Furthermore, with 
each new service you want to learn how 
to use, you must write new code, recom¬ 
pile, and then try to understand what 
went wrong if it doesn't work. These are 
expensive steps in an iterative learning 
process. 

When using an interactive develop¬ 
ment environment, you can try a service 
and immediately see its effects. You can 
change the service's parameters and see 
what effects these changes cause. It is 
also easier to work with Presentation 
Manager messages in an interactive en¬ 
vironment. Simply being able to exam¬ 
ine the Presentation Manager environ¬ 
ment at any time is a tremendous 
learning aid. 

An interactive development envi¬ 


ronment makes it convenient to explore 
questions like, I wonder what happens 
if I change the contents of the options in 
an accelerator table entry? It also makes 
it easier to explore Presentation Man¬ 
ager's Jess widely used but most power¬ 
ful facilities, such as arbitrary unit pre¬ 
sentation spaces and retained graphics. 

APL2 is a general-purpose program¬ 
ming language used in a wide variety of 
disciplines. APL2 is an interpreted lan¬ 
guage and provides an interactive appli¬ 
cation development environment. APL2 
for OS/2, also called APL2/2, includes 
an interface to Presentation Manager 
that can be used to interactively develop 
Presentation Manager applications. This 
article illustrates how von can easily ex¬ 
ploit some of Presentation Manager's 
most powerful facilities using APL2/2. 

THE APL2-PM INTERFACE 

The APL2/2 product's several compo¬ 
nents include a language interpreter, a 
session manager, and an auxiliary 
processor, called AP145, that provides 
an interface to Presentation Manager. 
The session manager provides a win¬ 
dow through which you communicate 
with the language interpreter and 
AP145. APL2 components communicate 
by using a special class of variables 
called Shared Variables. A shared vari- 
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able is a piece of data that is common to 
or shared between two components. 

A separate Presentation Manager 
environment is managed for each vari¬ 
able you share with API45. Each envi¬ 
ronment includes a separate thread and 
message queue. API45 monitors these 
queues and dispatches their messages. 
Most messages are immediately dis¬ 
patched to the appropriate default win¬ 
dow procedure. Only messages specifi¬ 
cally requested by the application are 
processed in APL2. 

AP145 supports many OS/2 ser¬ 
vices, including most of the Ddf y Dev, Dos, 
Drg, Gpi, Prf, $pl, and Win services. 

To call a service, assign the shared 
variable an array containing the service 
name and any parameters required by the 
service. To retrieve the service's return 
code, you reference the shared variable. 
Here is an example of calling a Win service 
and retrieving the service's results: 

SV145- 'WinShowWindow' HANDLE TRUE 

(APRC OSRC CMD)>SV145 

Note: In APL2, a left-arrow symbol 
assigns the value on the right to the 
variable name(s) on the left. 

For comparison purposes, here is 
the analogous call in C: 

Rc = WinShoyWindou(HANDLEJRUE) ; 

The APL2 and C methods both use 
the same Presentation Manager con¬ 
stants and service names that are docu¬ 
mented in the Presentation Manager ref¬ 
erence manuals. 

The differences are that APL2 al¬ 
lows you to call the service interactively, 
and it will run asynchronously. You can 
continue with other processing before 
referencing the shared variable. 

Each reference of an A PI 45 shared 
variable returns a three-element array. 
The first element is an auxiliary proces¬ 


sor return code. This code is zero unless 
an error is encountered, such as an in¬ 
correct number of parameters. The sec¬ 
ond element is the return code of the 
service. The third element is the service 
name and its parameters. Services can 
update their parameters, so the values 
may be different from those originally 
assigned. 

CREATING A WINDOW 

To demonstrate how AP145 can be used 
interactively, the following examples 
show how to create a simple window 
and draw some graphics. You can type 
these commands directly into the 
APL2/2 session manager and watch 
Presentation Manager process the ser¬ 
vice calls. 

First, share a variable with AP145 to 
establish a connection with Presentation 
Manager, The SVOFFER routine can be de¬ 
fined using an APL2 COPY command, 

)C0P¥ 1 UTILITY SVOFFER 
145 SVOFFER 'SV145' 

The first service to call is 
WinRegisterClass to register a class for a 
window that you can work with. The 
CS_SI2EREDRAW variable, and the other Pre¬ 
sentation Manager constants used in this 
article, can be set using a COPY command. 

KOPY 2 PM WIN CS.SXZEREDRAW 
CLASS*"APL2 Client Class' 
STYLE-CS.SEEREDRW 

SV145- 'WinRegisterClass' 0 CLASS 0 STYLE 0 

Now, call WinCreateStdWindow to create 
a standard frame window, as shown in 
Figure 1; for the client class, use the class 
name you just registered. This will cause 
a standard window to appear on your 
desktop. 

The FCF.SHELLPOSITION flag causes 
your window to be created with a stan¬ 
dard position and size. However, it does 
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Figure 1 . Calling VinCreateStdyindov to create a standard frame window. 



not automatically place your window on the top of 
all the other windows on your desktop. To bring it to 
the top, use the WinSetWindowPos service: 

FUGS-SWP.SHOV + SVP.ACTIVATE + SWP,ZORDER 
S V145- ' WinSetW indo v P o s' FRAME HYND.TOP 0 0 0 0 FUGS 

If you are trying these examples as you read, you 
will see that the client area of the window you just 
created is transparent because you have not yet 
drawn any graphics in it- To make it easier to see the 
effects of your calls to Gpi services, you may want to 
use your mouse to reposition the window now. 

To draw in any window, you need a device con- 
text and a presentation space. A device context is a 
connection to a particular device like a display A 
presentation space is a virtual coordinate space asso¬ 
ciated with a device context. You can draw graphics 
and text in a presentation space without worrying 
about device dependencies. Presentation Manager 
manages the conversions from the presentation space 
to the physical device. 

Creating a device context can be quite compli¬ 
cated, but Presentation Manager provides a very sim¬ 
ple service that will open a device context that is al¬ 
ready associated with your window. It is called 
WinOpenWindowDC: 

SV145* 'WinGpenWindovDC * CLIENT 
(A PRC DC CMD) SV145 

: l , j 

Now you can create a presentation space. To 
make the presentation space easier to work with, you 
can define an arbitrary coordinate spacb. The exam¬ 
ple defines a range of 0 to 10Q0 in both the X and Y 
directions: 

PSSIZE SIZEL CAST 1001 1001 
FLAGS- PU_ARBITRARY + GPIA_ASSOC 
SY145- 'GpiCreatePS' 0 DC PSSIZE FLAGS 


(APRC PS CMD) SV145 

The presentation space now exists and you can 
draw on it, but by default, it is mapped to the entire 
display screen. To have your space mapped to the 
client window, you must set the page viewport to 
match the client's size and position. To do this, query 
the rectangle surrounding the client and set the page 
viewport to match this rectangle: 

RECTANGLE- RECTL CAST 0 0 0 0 

SV145 'WinQue ryHindowRect' CLIENT RECTANGLE 

(APRC 0SRC CMD)- SV145 

(API CLIENT RECTANGLE}' CMD 

SV145- 'GpiSetPageVieuport' PS RECTANGLE 

Now you're ready to actually draw in your client 
window. You can use all the Gpi services and your 0 
to 1000 coordinate system. Presentation Manager will 
clip and scale your graphics to the client area. 

To start, try setting the color and drawing a box 
that fills the entire client area: 

SV145 'GpiSetColor' PS CLR.BLUE 

POSITION POEMTL CAST 0 0 

SV145- 'GpiMove' PS POSITION 

CORNER- PDINTL CAST 1000 1000 

SV145 'GpiBox' PS DROJHJTLINEFILL CORNER 0 0 

Now try changing the color and drawing a 
smaller box with rounded corners: 

SV145* 'GpiSetColor' PS CLR_RE0 

POSITION- POINTL CAST 100 100 

SY14S- 'GpiMove' PS POSITION 

CORNER POINTL CAST 900 900 

SY145- 'GpiBox' PS DR0_DOTLINEFILL CORNER 50 50 

Next, change the color once more and draw some 

text: 
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5Y145> "GpiSetColor' PS CLR_GREEN 
POSITION’ PQINTI CAST 450 500 
5V145* 'GpiMove' PS POSITION 
SV145- "GpiCharString" PS 11 'Sample Text' 


you need to close and destroy it. The following state¬ 
ments inform AP145 that you want the messages cor- 
responding to these events to be passed to APL2 for 
processing; 


Using your presentation space, you can try some 
of the other Gpi services. GpiErase, Gpiline, and GpiMarker 
are all useful and easy services you might try. 

As you can see, you can accomplish a lot calling 
OS/2 services interactively. You can create windows 
and experiment with the Presentation Manager ser¬ 
vices and structures. Eventually, however, you need 
to respond to user input; you need to process 
Presentation Manager messages. Fortunately this too 
can be done interactively. 

PROCESSING PRESENTATION MANAGER MESSAGES 

AP145 provides several 'ApT services that are used to 
redirect messages to APL2 for processing. The proce¬ 
dure is to tell API 45 what messages you want to 
process and then wait for them. 

Your example window needs to respond to three 
events: size, paint, and close. When a size change oc¬ 
curs, you need to reset your page viewport so your 
coordinate system is mapped to the new window 
size. When part of your window has been invali¬ 
dated, you need to repaint the invalid area. And 
when the user requests that the window be closed. 

Casting APL2 Arrays 

APL2 arrays are stored in an internal format that 
is different than Presentation Manager uses. 

Before using an APL2 array as an API parameter, 
the array must be converted to Presentation 
Manager's format. 

A program is supplied with APL2, which can be 
used to convert arrays from APL2's to Presentation 
Manager's formats. Here is how to make it avail¬ 
able to your session: 

3 li DNA 'CAST ATR' 

The following shows how to build the variables you 
will need to cast the arrays used in this article: 

LONG- '14 0 ' 

POINTL-'GG 1 2 '.LONG,LONG 

RECTL-'GO 1 4 '.LONG.LONG.LONG.LONG 

SEEL- 'GO 1 2 '.LONG,LONG 


SV145 'AplRegisterHsg' CLIENT WM.PSIZE 0 0 

SV145- 'AplRegisterNsg' CLIENT WM.PPAINT 0 0 

SV145- 'AplRegisterNsg' FRAME WM_SYSCOMMAND SC.CLOSE 0 

Once the messages you Ye interested in have been 
registered, you use the AplWaitMsg service to wait for 
messages. AplWaitMsg updates its four parameters with 
the handle, message identifier, and message parame¬ 
ters 1 and 2: 

SV145 'AplWaitHsg' 0 0 0 0 
{APRC OSRC CMD)SV145 
(SERVICE HANDLE MSG MP1 MP2) CMD 

The last expression in the previous example will 
extract the window handle, message identifier, and 
the two message parameters from the result returned 
by AP145. You can compare the message identifier 
with any of the standard message identifiers to deter¬ 
mine which message has been returned. For example, 
the following line of code yields a vector of Boolean 
values, which indicates that the message is a 
WH.SVSCOHHAND message; 

MSG=WH_PSIZE WM_$YSC0MMND WM.PPAINT 
0 1 0 

When you receive a WM.PSIZE message, the size of 
your window has been changed. For your coordinate 
system to continue to work, you should query the 
client window rectangle and set the page viewport 
just as you did initially. 

Presentation Manager sends you a WM^PPAINT mes¬ 
sage when part of your window has been invalidated 
and needs to be redrawn. This can happen when part 
of your window has been covered and then exposed 
by movement of another window, in response to a 
UM_PPAINT message, you should redraw the invalid 
area and tell Presentation Manager that the invalid 
part of your window is now valid so it does not keep 
sending you WM.PPAINT messages. 

To redraw the graphics, you can simply issue all 
the graphics calls again. Alternatively, you can use 
retained graphics to have the same effect more easily 
and quickly. 

First, set the drawing mode to retained so you 
can draw graphics once and reuse them. 

SV145- 'GpiSetDrawingMode' PS DM.DRAWANDRETAIN 
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Now open a segment, redraw your graphics as 
you did before, and then dose the segment. When 
using retained graphics, once a segment contains 
graphics, you can draw the segment at any time and 
all the graphics will be redrawn. Following are the 
calls you use to open, dose, and draw segments: 

SEGMENT 1 

SV145- 'GpiOpenSegment' PS SEGMENT 
SV145 'GpiOLoseSegment' PS 
SV145 'GpiDravSegment' PS SEGMENT 

Now you're ready to efficiently handle WM_PPAXNT 
messages, Here's some code to query the invalid rec¬ 
tangle, tell Presentation Manager it's valid, and draw 
your segment: 

RECTANGLE RECTI CAST 0 0 0 0 

SV145- 'WinQueryUpdateReel' CLIENT RECTANGLE 

(APRC OSRC CHD) SV145 

(API CLIENT RECTANGLE) CMD 

SV145-'WinValidateRect' CLIENT RECTANGLE TRUE 

SV145 'GpiDrawSegment' PS SEGMENT 

Finally, you also need to respond to WM^SYSCOMMANO 
messages. You can verify that the message actually 
corresponds to a close request from the system menu 
by examining the first message parameter. When 
you're done, you can simply destroy your window: 

MP1=SC_CLD$E 

I 

SV145- 'HinDe s t ro y Win do u' FRAME 

When AplWaitMsg returns a message, you can call 
as many Presentation Manager services as you want 
and even continue to interact with your window be¬ 
fore returning a message result. Messages that are re¬ 


ceived while you are processing a message are held 
until the next call to AplWaitMsg. Once you are done 
processing the message, you can use ApIReturn to re¬ 
turn a result or you can use AplWaitMsg to return a re¬ 
sult and wait for further messages. 

SUMMARY 

In this article you've seen how to build a simple win¬ 
dow that uses some of the OS/2 Presentation 
Manager's most sophisticated facilities, including ar¬ 
bitrary unit presentation spaces and retained graph¬ 
ics. Using an interactive approach gives you a conve¬ 
nient way to explore Presentation Manager's many 
services, and APL2 is an excellent tool to do this. 

David Liebtag, IBM Corp., San Jose, Calif, is an advisory pro¬ 
grammer in IBM's APL Products and Services group. David's 
recent work has focused on the Presentation Manager facilities 
in the APL2 for OS/2 product. This work has included the session 
manager editors , printing facilities, and the AP12-PM interface 
processor. David can be reached via Internet at 
Iiebtag@stlvm20wnet ibm.com or CompuServe at 73164,623. 
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Product Watch 


New Products for OS/2 


BexxBase 1.34. This is an OS/2 dynamic link 
library (DLL) that allows REXX command pro¬ 
cedures to create databases using dBase file for¬ 
mats. File allocation table (FAT) and High 
Performance File Systems (HPFS) are supported; 
RexxBase uses the REXX application program 
interface* 

American Coders Ltd. Circle No. 151 

Phone: (919) 846-2014 

PowerPak for OS/2, This add-on utility is 
designed to complement OS/2 Warp 3. 
PowerPak has a full-featured program sched¬ 
uler that enables users to launch various pro¬ 
grams based on user-defined time intervals. 
The scheduler provides a clock and calendar 
for the OS/2 desktop, PawerPak's import and 
export facility helps users share data between 
OS/2 applications such as faxes, personal infor¬ 
mation mangers, and databases* 

Arcadia Technologies Inc, Circle No. 152 

Phone: (818) 446-6945 

Extra! for OS/2. This host connectivity software is 
32 bit, object oriented, multithreaded, and com¬ 
patible w ith Warp. Extra! for OS/2 supports 
advanced program-to-program communication 
and a wide range of productivity features, 
including integrated batch file transfer, macros, 
SmartPad, Hotspots, drag-and-drop keyboard, 
and color remappers. 


accounting systems. It is aimed to be high per¬ 
formance and still cost-effective* 

Avista Software Circle No* 154 

Phone: (404) 564-8015 

BBN Internet Server, This UNIX server has the 
ease of use of BBN's graphical user interface- 
based software that runs on Apple Macintosh 
or Microsoft Windows desktops. The server 
supports all Internet-protocol client platforms, 
including Windows, Macintosh, UNIX, and 
OS/2. It provides access to widely used 
Internet server functions including World Wide 
Web (WWW) database servers, e-mail, Gopher 
database servers, FTP file retrieval servers, and 
Network News bulletin boards. 

BBN Circle No. 155 

Phone: (800) 632-7638 or (617) 873-8730 

DataLink for Lotus Notes* This is a cost-effec¬ 
tive, point-and-click solution for migrating and 
synchronizing data between Lotus Notes and 
other major relational databases. DataLink does 
not require scripting or programming. It offers 
complete server-platform independence and 
provides access to data stored in Lotus Notes 
3.0 or higher servers running Windows, OS/2, 
UNIX, orNLM* 

Brainstorm Technologies Circle No, 156 

Phone: (617) 492-33 99 


A tta chmate Corp, C i rcl e N o, 153 

Phone: (206) 649-6551 


Avista , This fully integrated, multiuser, 
client/server accounting and business manage¬ 
ment software solution runs on DOS, OS/2, or 
UNIX, Avista is based on a customizable rela¬ 
tional database specifically designed to aggre¬ 
gate high-volume transactional data typical to 


Preditor/2. This graphical, 32-bit editor is 
equipped with the ability to display multiple 
windows, search across multiple files, edit and 
compile simultaneously, and emulate other edi¬ 
tors. It is customizable—programmers can 
jump to variable declarations, class definitions, 
or start functions, 

Compuware Corp, Circle No. 157 

Phone; (810) 737-7596 
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VisuaiGen. This application development tool 
for business-critical applications allows pro¬ 
grammers to develop client and server code 
concurrently for use on workstations and the 
host. Users can take advantage of cooperative 
processing. The company claims its product 
brings new functionality through support for 
Windows clients and C++ application genera¬ 
tion for OS/2 and AIX. 

IBM Circle No. 158 

Phone: (914) 766-1211 

Visual SlickEdit for OS/2. This programmers' edi¬ 
tor offers procedure tagging, multiple clip¬ 
boards, and compiler error processing. It pro¬ 
vides the user with a macro language called 
Slick-C as well as a DLL interface for extending 
the editor* Visual SlickEdit supports C/C++, 
Pascal, Fortran, Basic, dBASE, Modula-2, 
assembly language, COBOL, and Ada. 

m icro Edge Ci rcle No. 159 

Phone: (919) 790-1691 

NDP Pentium Compilers, These compilers 
run under DOS and OS/2. They are available 
for Fortran, C/C++, and Pascal. They drive 
RISC, CISC, and Vector devices. The new com¬ 
pilers add Pentium scheduling, the use of 
FXCH instructions to streamline x87 stack 
accesses, and a new peepholer that results in 
smaller code. Other features are dynamic link¬ 
ing, loop unrolling, numeric register caching, 
and numeric register coloring. 

Microway Circle No. 160 

Phone: (508) 746-7341 

Wizard O.S* 1*0, This multi-operating-system 
boot utility a Hows users to choose between 
DOS, Windows 95, OS/2, Windows NT, and 
UNIX at boot time. The user can have multiple 
versions of DOS or OS/2 and thus have differ¬ 
ent configurations of a particular operating sys¬ 
tem. One hundred different operating systems 
can be installed on the same hard disk. It does 
not require any special disk partitions like Boot 
Manager, nor does it require any disk parti bon¬ 
ing or formatting. 

Modular Software 

Systems Circle No. 161 

Phone: (800) 438-3930 or (206) 631-5781 


Quick/2 Install. This installation tool allows the 
entire OS/2 operating system to be installed in 
less than 15 minutes using quarter-inch car¬ 
tridge backup systems. Quick/2 is ideal for 
users who require the ability to perform several 
installations or who desire an ** unattended" 
installation. 

Parallel Storage Soludons Circle No. 162 

(914) 347-7044 

QbjectPro. This is an object-oriented develop¬ 
ment tool for building robust client/server 
applications. The company announces that ben¬ 
efits include intuitive modeling, code reuse, 
and productive maintenance that applies to the 
whole business model—business logic as welt 
as screens and database interaction. ObjectPro 
supports Oracle and Sybase through native 
interfaces, ODBC drivers are provided that 
support Ingres, SQLBase, DB2/2, Allbase, 
dBase, Access, FoxPro, and so on. 

Trinzic Corp. Circle No. 163 

Phone: (617) 891-6500 

GUI-Kit. This C and C++ cross-platform GUI 
development toolkit supports 32-bit develop¬ 
ment under Win32, Windows NT, OS/2, and 
UNIX/Motif. This object-oriented program¬ 
ming environment can he used in C or C++. 

Visual Systems Corp* Circle No, 164 

Phone: (612) 434-6382 

The Graham Utilities for OS/2 , New utilities are 
added to the already strong suite of over 30 
applications. The user can recover multiple 
deleted files in one step and recover files from 
damaged or unusable High Performance File 
System partitions. Two file defragmenters are 
included. 

Warp Speed Computers Circle No. 165 

Phone: 61 3 384 1060 

Mathematica 2.2. Wolfram Research announces 
the release of a native version of Mathematica 
2.2. The new version takes advantage of OS/2 J s 
32-bit environment and runs faster* It is com¬ 
patible with OS/2 Warp 3,0* 

Wolfram Research Inc. Circle No. 166 

Phone: (217) 398-0700 
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Buyer's Guide 


The staff of OS/2 Developer put together this special section to guide you through the various software 
tools specifically for the performance tuning, testing, and debugging of OS/2 applications. The products 
described in this guide are based on surveys sent to vendors; they are provided as a service to you and 
are free to vendors. These listings do not represent an endorsement by OS/2 Developer. Although every 
effort has been made to ensure accuracy, we do not assume any responsibility for error or omission in 
this section. 


Testing and Debugging Tools 
Buyer's Guide 


A UTOTESTER Circle No. 101 

AutoTester for OS/2 2.02 is an automated testing 
tool designed specifically for OS/2 Program 
Manager applications. AutoTester builds 
structured, object-oriented, and documented 
tests as you operate an application. Thus, the 
user gets a flexible, reusable, and maintain¬ 
able test library that can be executed unat¬ 
tended. It supports the skilled developer and 
expert application users. Price: $5,000 per 
copy with quantity discounts, 

AutoTester, 8150 N. Central 
Expressway, Ste. 1300, Dallas, Tex. 75206, 
(800) 328-1196 or (214) 368-1196, fax (214) 
750-9668. 

BON AMI Circle No. 102 

CPU Monitor Plus 2,31 is an OS/2 Performance 
Monitor and Analysis package. It displays 
real-time CPU, RAM, Disk, Interrupt, and 
COM port activity. It will diagnose poorly 
running systems, set execution priorities, 
and log performance data for later analysis. 
It can start, stop, or suspend programs and 
has over 100 different metrics and ratios. 
Price: $129.95. 

Bon Ami, 60 Thoreau St. Ste. 219, 
Concord, Mass. 01742, (508) 371-1997, fax 
(508) 371-2333. 

CARRY ASSOCIA TES Circle No. 103 

Sys Maint 3.3is a 32-bit Presentation Manager 
application that provides a full desktop diag¬ 
nostic and a backup and repair utility. It iden¬ 
tifies and fixes a number of common Desktop 


problems, provides a desktop backup and 
restore, allows the user to edit, copy, move, 
backup, search, compare, size, repair, and 
maintain any INI file, including the 
OS2SYS.INI and QS2.JN1 files. It will view, 
copy, move, split, join, test, compare, and 
maintain extended attributes, including the 
desktop directory structure. Price: $49.95 
plus $7.00 shipping and handling. 

Carry Associates, 990 Jronwood Ct., 
Marco Island, Fla. 33937-4458, (813) 642- 
9126, fax (813) 642-1007, 

CLIENT SERVER 

NETWORKING INC Circle No. 104 

WATCHIT2.0 optimizes IBM LAN platforms 
(OS/2, AIX, MVS/VM, and AS/400), 
WATCH IT collects statistics about resource 
and user activity and analyzes the data. It 
automates collection of IBM LAN server 
capacity and performance statistics to help 
improve performance and anticipate capac¬ 
ity problems. Collection may be automated 
at the server or manually controlled from 
your desktop. Price; $349. 

Client Server Networking Inc,, P.O. Box 
370111, West Hartford, Conn., 06137-0111, 
(203) 233-2951, fax (203) 233-2951. 

IBM CORP Circle No. 105 

Workstation Interactive Test Tool (WITT) 2X2 is 

a capture and playback tool for automating 
unit and regression testing. WITT records 
keystrokes, mouse movements, and screen 
images as you step through your application 
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to automatically generate test scripts* WITT 
can also be used to automate many activities 
such as giving demos, entering operator com¬ 
mands, starting and stopping subsystems, 
system testing, and simulating users for disas¬ 
ter recovery* WITT installs on the OS/2 desk¬ 
top and allows testing of Host, OS/2 
Presentation Manager, and Text applications. 

IBM Corp., 555 Bailey Ave., San Jose, 
Calif, 95141, (BOO) 426-4785 or (408) 463-2000, 
fax (800) 426-4522. 

MERCURY INTERACTIVE CQRP Circle No. 106 
WinRunner for OS/2 is an automated testing 
tool for OS/2 applications that compresses 
manual testing into a single overnight run. It 
tests OS/2 applications in any programming 
language. WinRunner includes automatic 
GUI verifications, inside testing beyond the 
graphical user interface, output synchroniza¬ 
tion, text recognition, object-oriented record 
and replay, and reusable and portable tests. 
Price: $2,850. 

Mercury Interactive Corp*, 470 Portrero 
Ave*, Sunnyvale, Calif* 94086, {800} 837-8911 
or (408) 523-9900, fax (408) 523-9911. 

MICROQUILL SOFTWARE 

PUBLISHING INC Circle No. 10? 

Smart Heap 2.2 is a fast (3X-1G0X), portable, 
reliable ANSI-compliant, and malloc-free 
library. It is thread-safe and supports multi¬ 
ple memory pools and shared memory. 
SmartHeap provides heap error detection 
and detects bugs other tools miss—leakage, 
overwrites, double-trees, wild pointers, out 
of memory, and references to previously 
freed memory. Price: $695* 

MicroQuill Software Publishing Inc., 
4900 25th Ave. N.E., Ste. 206, Seattle, Wash. 
98105, (800) 441-7822 or (206) 525-8218, fax 
(206) 525-8309. 

PERISCOPE COMPANY INC. Circle No. 108 
Periscope/32 for OS/2 5.4 is a device driver 


debugger for OS/2 v. 2*x* This full-screen, 
symbolic, source-level debugger helps devel¬ 
opers of OS/2 2.0 Base and Presentation 
Manager drivers. It operates at the systems 
level, has easy access to any memory loca¬ 
tion in the system, and is compatible with 
applications level debuggers* It includes host 
and target system software and a break-oul 
switch for crash recovery. 

Periscope Company Inc., 1475 Peachtree 
St., Ste. 100, Atlanta, Ga* 3D309, (800) 722- 
7006 or (404) 888-5335, fax (404) 888-5520. 

PROGRAMART CQRP. Circle No. 109 

APMPower 2.0 is an OS/2-based product that 
facilitates the analysis of MVS application 
performance data. Operating with 
Programart's STROBE application perfor¬ 
mance measurement system, APMPower is 
used to pinpoint and resolve application per¬ 
formance problems before they enter pro¬ 
duction. It enables users to freely share 
application performance knowledge, 
improving IS productivity and application 
quality. Price: $2,000 for single user, $4,000 
for current-use licenses* Volume discounts 
available* 

Programart Corp., 124 Mt. Auburn St., 
Cambridge, Mass. 02138, (617) 498-4045, fax 
(617) 868-6069. 

S0FTBRIDGE INC * Circle No. 110 

Automated Test Facility 15 tests client/server 
and stand-alone OS/2, Windows, Windows 
NT, and legacy (via 3270 emulation) applica¬ 
tions* ATF's two-tie red architecture supports 
true client/server testing* From one central 
point, ATF can run intertwined, simultane¬ 
ous, unattended tests on multiple PCs, testing 
all client/server layers—graphical user inter¬ 
faces, distributed applications, and legacy 
systems. Price: $18,000 for base system. 

Softbridge Inc., 125 Cambridge Park Dr*, 
Cambridge, Mass, 02140, (800) 955-9190 or 
(617) 576-2257, fax (617) 864-7747. 
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SOFTOUCH SYSTEMS INC Circle No . 111 
Gamma Tech Utilities 3.0 for OS/2 Warp 
accelerates disk performance, performs 
High Performance File System (HPFS) 
optimization on line, and defragments 
file allocation table {FAT} files without 
crosslinking their extended attributes. 
Functions include desktop backup, disk 
analysis, boot sector backup, restore, 
and virus protection. Price: $99. 

SofTouch Systems Inc., 1300 S. 
Meridian Ave. Ste. 600, Oklahoma 
City, Okla. 73108, (405) 947^8085, fax 
(405) 632-6537. 

2500AD SOFTWARE INC Circle No. 112 
2500AD S inw la to f/Debugger 5 is a full- 

color, menu-driven debugger. It debugs 
C and assembly language source code. It 
features stack control, memory traps, 
and control of registers, flags, memory, 
and variables. Price: $150. 

25 00 AD Software lnc + , 109 
Brookdale Ave., Buena Vista, Colo, 
81211, (800) 843-8144 or (719) 395-8683, 
fax (719) 395-8206 


VERITAS SOFTWARE CORP. Circle No. 113 
VistaTest supplies the basic tools 
needed to immediately improve detec¬ 
tion and elimination of latent defects. 
Vista TEST provides quick insight into 
what part of mission-critical applica¬ 
tion code has not been exercised by 
existing test suites. Dynamic coverage 
includes predicate, conditional, block, 
and/or path levels of code coverage. 
The product supports the 1BM C Set 2 
and C Set ++ compilers, including tem¬ 
plates and exception handling. Price: 
VistaTEST (C), $1,800; VistaTEST 
(C/C++), $2,800. 

Vista SIM simulates interface 
behaviors. Using either prepackaged 
OS calls or customized libraries cre¬ 
ated with the VistaSim Simulation 
Builder, this functionality allows for 
testing of difficulMo-reach code. Price: 
$3,200, 

VistaGRAPH is a general-purpose 
graphing tool that provides presenta¬ 
tion graphics of charts, line plots, and 
kiviat diagrams. These charts provide 
clear visual representation of test 
results, 

VERITAS Software Corp., 4800 
Great America Parkway, Santa Clara, 
Calif, 95034, (800) 258-8649 or (408) 
727-1222, fax (408) 562-4334. 
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ATS 

Version 3.0 



Are /ju looking for a way to 
manage your production job 
streams? Do you have proyams 
that need to run after the 
completion of one or more other 
programs? Do you want to run 
programs on a regular basis? Do 
you want to process files that 
have just been received from 
another system or modified 
locally? Do you need to take action 
if a file is missing? Do you need to 
schedule around holidays and 
periods of heavy CPU toed? 

With ATS you can run your 
programs when YOU went them 
to run with out you having to be 
there. 


OpO rP vIr** e>n v , 

o'* 1 *! 3227 


Here are same of the features of 
ATS for OS/E: 

* Manage Production Job 
Streams 

* Programs can be scheduled to 
run anytime. 

* Programs can be dependent 
upon Files. Other Programs, 
Holiday Schedules, and 
External Signals 

* Integrated Operators Console 

* Logging-To File end Console 
New Features: 

* Job Queues-for managing 
your resources while managing 
your tasks 

* Periodic Scheduling 

* COMPLETE A PI and Command 
Line Interface 

Only 


$349/ 




Voice (908) 821 


Software and Consulting 
2227 US. Highway #1 "Suit* 146 
North Brunswick, NJ 08902 

0359 * Fax:J908^82ri0350 * CompuServe 70312,627 
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Visual 


THi INTELLIGENT 
PROGRAMMER'S 
EDITOR 



$ 1 99 
SPECIAL OS/2 
INTRODUCTORY 
OFFER! 


OS/2 

WINDOWS 
WINDOWS NT 


Winners of Software 
Development Productivity Award 


Visual SlickEdit™ is the high 
powered programmer's editor with the speed, 
ease, and features you need to ignite your 
productivity. Learn in no time with our 
comprehensive CUA, Brief, Emocs, and VI 
emulations. Take off with our extensive 
language support, project management, and 
NEW SmartPaste rw . 

Powerful fealures: 

* Incremental search/search and replace 

* Completely configurable 

* Spell check comments and strings 

* Typeless, object oriented, C-style macro language 

* Built-in dialog editor 

* Clipboard Inheritance 11 ' (potent pending) 



Col your work In half using: 

Procedure togging 

Syntax color coding, expansion and indenting 
SmolPaste reindents posted source code according to 
nesting level 

Compiler error processing 


V&wl Skktdri hi ppoTfr t''T++. tewt fas*. Moduh’2, Asiefobty. 

COBOL and Ad a. the HMow tfi vs row * thmfaW* for M- Mips. 0** &¥* 

Uf mMm. To Qrc | er Ca || 800-934-EDIT oko (919) 831 0400 or FAX (919) 831 0101 

fed SfakEfc. Wfel*. u4 OotM'd Inh.nnmi or, ndUMMfcl d Ufowdp. w»fcn 10. Mips. h d ihelr I«p*i* 


MicroEdge, Inc. PO Box 18038, Raleigh, NC 27619-8038 USA 


OS/2 DEVELOPER 


































POWER i!jp with 

THE RIMSTAR PROGRAMMER’S EDITOR 

NEW VERSION 2.1 




go*** Baffin W*jndw * gp*™* Help 






D i.PXlLmi \C\£AMFt£ S'^fWrr.r’i.^aphtf: t~ 


* ft* Uiiilnit ial ize rmt inc fnll U 1 Mws. trte Pr«wnta 1 ifxn *%r 

* feel 1 itics (nr iiw tKJ ITils appl ical imi sri nrtufrta I Iuf4i 

* mdw block Msirjueti id Tt* 4K»Uc4flon by PM. 

*/ 

If ttPJrM-lifB - Ulnlniltatizeiei) — 
rpturMFALSE); 

flw nwpiTJUe - fictStrinofParR.MHI, iM^Pi I CAT I nrt rtfirtf. , ft 

if* flip UiiCrnile^u^Quogp e*U creates a nessaat' i^wn» far tij 

Jir (iFMin nrtQ . yirCrpetrrHyfkM-uefPACA I*W r I63B4)] ** tfM). 
return(FALSE); 

/* Query Syaten Wlnlw */ 

Parn.npIrUlass * UlnfluPruSusPointer tMW*_DeSKTDP, SFT^MHT, 
Parn.hptrftrrOii ■ «in(^ri>Sysl>iQlnterfHyM!)_D€SieTOI» J SPTH^f 


* a - 

f DCD 34 ) M I ikrf i, H. flLLDCjSI RIHU 1 
p u,hi Fin* STPTlC^STPJMq a 

||j[/* Structure-Opr IfFJtiufrs *7 


» D 


Kftef Struct PHTTX 1 DATA \ 
psi *?PHt; 

CHFIH f|p«-uHi»e[!2]; 

Dt ivpfHawIMiifFHW l FnCiTHI , 


WOIB 


DriwfDitd; 

IVUnaV r,irrt L ; 

JatrameLB]; 


f* DflUfF'P 


/* flip Follnilix) f\mctl« r roisters the :l«ws uf *U kH>U 

si reput GPt St r lnq (Pam. Hf®„ flPPl I CAT IOH Hfltif. Sfflf 

rc ■ UljiRrflstrrCLawfPwii. ME, /* fhcltor block Fume 

[PCM)azfljKsNanpj /* Hanp of el*W 


CHf* 

L |»ITJET EVltCb' 

lUPtlicf PRlTKT_»Ifi *P«ITTXl_KlTfi; 

Structure far C-A^lng defaults •/ 

typodpf struct PPL_Dtf ML T£ ( 

UL DUG cu; 

lUJHfh CM; 

CMW Diiyprn™v?rt 3 ftHJEfiikW I.FHtilH]; 

> (WL -DCF fltJL 1 TJj 

tvpcde? «M*._D£FMJUS *f>flPPl. DEFfKJUS; 


'jtuptdrf struct 
LOHG 
1_0MG 


RESOLUTION I 


tPfflklPJUhdPrCE, 7 » Uliklou grocedu ri? v | HFSm LFflDW; 

> One: 2GB Column:^ ' ;;tt,i»dcr sesoluiigfi *«tFsa.uTiow: 
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tiCMUUOW 

JQQMXWSD 

00000060 


WOOOpTO: 


GEIFMQE -TJOfMCHCO 7IBSDI4C iJJZlS'iba Jffefjt ^!*GL-ITft 
frqiJZOTQ fjwazf? bStrarhl is program carwro 

iGH&ZhS J0TZ'f5tF 2K41E2D hlZMflF t 1» run In .1 HO 


|K!Wgag l * , ' l> - 

Exaction ic*l 2 C £a(7? Syntax Ctiidt0 VFddXT?1 C 


O V* fir;ru Pewter */ 

tifpdpf struct (HUU PWBf ( 

RECH rclttxndsj 7* Bonding I 

EMOt iflllUdtidj /* hrjjninval 

BOOL fpratting; __ / > ft^jpichrik^ 

j Una 59 ColirtttFv: I 


If you're looking for a fully configurable professional OS/2 PM 
programmer's editor to replace your current text-mode editor - we 
have what you have been looking fori 

No hassle changing editors 

We know changing editors can be a major hassle. You don't want 
to relearn a new set of keystrokes no matter how good the product. 
Well, you don't have to - we have Brief, CUA, Epsilon, Multi—Edit, 
SlIckEdit, PWB, and Borland IDE keyboard mapping waiting for you. If 
you're not using one of these, let us know and we will create the 
mappings you need. 

Features designed to increase productivity 
It has all the features you have come to expect plus special 
features designed to anticipate your needs and Increase your 
productivity. Features like a l C' source browser that eliminates those 
time consuming searches for functions global variables lypedefs, 
and macros by providing you with instant positioning to both 
definitions and references Using our powerful 'C' macro language 
you can customize your programming environment to suit your 
Individual needs. 




Partial Feature List 

S Complete ANSI *C' macro language 
>/ SyntaCofor^—syntax highlighting 
v Smart C/C+ + indenting & brace matching 
Bookmarks 

>/ Unlimited undo and redo 
Timed auto save 

v' Access PDK help for function under cursor 
y Multi-threaded for no waiting 
y Compile and jump to errors 

Import/export to system clipboard 
</ Keystroke record/playback 
^ Block indent/outdent 
y Hex editing 

V Customizable menus 

V Column, line and block 
selection, search and replace 

V Integrates with Workframe/2 
S Source browser for *C' 

^ Template editing 

J Multi-buffer regular expression 
search and replace 

'Z Support for version control 

'Z Complete on-line help 

Z Save and restore state between sessions 

Z OS/2 2>x 32 bit PM Multi-document 
Interface 


'My copy of Brief hos been permanently 
retired. Keep up the good work!* - AL 


RimSfar Technology, Inc. 

91 Halls Mill Road 
Newfields, NH 03856 
Voice: (603) 778-2500 
Fax: [603) 778-2408 
BBS: (603) 778-4644 


Price $299.00 

Plus Shipping & Handling. 

To order call 1-800-746-7007 

60 day money-back guarantee. 

Also available for Windows and Windows A fT 


Ai products and company names ore 
trademarks of registered trademarks of ttietr 
respective holders HmStar and SyrrtaCoKx 
ore Irademartcs of RlmStar technology Inc, 


© 1994 RlmStar Technofogy Inc, 
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The Suite Way to Build 
Portable Applications 




I s building applications 
your job? Then life just 
got easier thanks to the 
zApp* Developer’s Suite 
for Windows. The zApp 
Developers Suite is a set of 
highly integrated C++ devel¬ 
opment tools designed to help 
you transform the blueprints 
in your mind into commercial 
quality applications—quickly 
and easily. And best of all, 
applications built using the zApp 
Developer’s Suite are portable to fourteen 
different platforms! 

The zApp Developer’s Suite consists 
of zApp, the award-winning portable C++ 
application framework; zApp Factory''', a 
fully visual application designer and code 
generator; and the zApp Interface Pack, a 
collection of high-level visual objects for 
the zApp environment. All of these tools 
are highly integrated to provide maximum 
ease of use and flexibility. 

Rapid Application Development. 

Introducing an exciting new visual tech¬ 
nology that lets you drag and drop a wide 
assortment of objects like toolbars, 
tables, and 3D dialogs; define their char¬ 
acteristics; and build interfaces of any 



zApp and Inmark are registered trademarks of Inmark 
Development Corporation. zApp Factory is a trademark of 
Inmark Development Corporation. OStt is a registered trade¬ 
mark of IBM. All other trademarks are the property of their 
respective owners. 

In the U K. and Scandinavia, call PTS.'Software Plus 
at *44 (0) 928 579900 

In France, call PTS Software Plus at (05) 908194 
In Germany, call ESM Software at 07022 9256-0 
In Italy. call Silicon Valley On-Line at (049) 654221 
In Australia, call Micro Way at (03) 5801333 
BBS 415-691-9990* Internet. »nln@ iiunark coin 
r-wiwuerw GO INMARK 


complexity; all in one powerful but easy 
to use environment. With the click of a 
button, you can engage a powerful test 
mode which lets you interact with your 
application, seeing it exactly like your 
end user will see it: letting you fill in 
dialogs, pull down menus, etc. When you 
are pleased with the look and feel of your 
application, fully commented C++ source 
code is only a mouse click away, thanks 
to the zApp Developer’s Suite’s code gen¬ 
eration capabilities. 

Object-oriented Power. 

The best news is that this development 
environment sits on top of zApp, the 
industry leading C++ application frame- 
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work, and the zApp Interface 
Pack, so you have all of their power 
at your disposal — toolbars, table 
objects, advanced graphics — in 
all, over 300 object classes of power 
just waiting to be tomorrow’s best¬ 
selling application. 

Portability and More. 

When you're done building your 
application, then you can decide 
what platforms you want to support! 
Applications built using the zApp 
Developer’s Suite are single-source portable 
to fourteen different platforms. By simply 
recompiling, your application will run 
natively on Windows, Win32 (Windows 
NT, Windows 95, and NT on the DEC 
Alpha), OS/2*, DOS Text, DOS Graphics 
and seven X/Motif platforms: IBM 
RS/6000 AIX, HP HPUX 9.x, SGI IRIX 
5.2, SCO UNIX, Sun Solaris 2.x, Sun 
SunOS 4.1 .x. Sun Solaris x86. 

Free Demo. 

Sound impossible? Well, if seeing is 
believing for you, call 1-800-346-6275. ask 
for our free demo disk, and get a glimpse 
of what the future has to offer. 

INMARK 

2065 Landings Drive, Mountain View, CA 94043 
T: 800-346-6275 or 415-691-9000 F: 415-691-9099 
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